source: trunk/kernel/libk/queuelock.h @ 690

Last change on this file since 690 was 666, checked in by alain, 4 years ago

Cosmetic.

File size: 4.5 KB
Line 
1/*
2 * queuelock.h: local kernel lock with waiting queue implementation.
3 *
4 * Authors  Alain Greiner (2016,2017,2018)
5 *
6 * Copyright (c) UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH.
9 *
10 * ALMOS-MKH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-kernel; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#ifndef _QUEUELOCK_H_
25#define _QUEUELOCK_H_
26
27#include <kernel_config.h>
28#include <hal_kernel_types.h>
29#include <busylock.h>
30#include <list.h>
31
32/*******************************************************************************************
33 * This synchronisation object sequencializes concurrent read or write accesses to a
34 * locally shared object in a given cluster (i.e. made by thread(s) running in same cluster.
35 * This lock has only two states: taken or free.
36 * When the lock has been taken by another thread T', the thread T executing the
37 * queuelock_acquire() function blocks and deschedules, after registering in the waiting
38 * queue rooted in lock descriptor. The first thread in the waiting queue will be unblocked
39 * by the owner thread executing the queuelock_release() function.
40 * To handle concurrent accesses between a thread T executing the acquire() function
41 * and a thread T' executing the release() function, the "queuelock" is protected
42 * by a "busylock" used by these two access functions.
43 ******************************************************************************************/
44 
45
46/*******************************************************************************************
47 * This structure defines a queuelock.
48 ******************************************************************************************/
49
50typedef struct queuelock_s
51{
52    busylock_t          lock;               /*! protect atomic access to queuelock        */
53        volatile uint32_t   taken;              /*! state : free if zero / taken if non zero  */
54    list_entry_t        root;               /*! root of list of locally waiting threads   */
55}
56queuelock_t;
57
58/*******************************************************************************************
59 * This function initializes a local queuelock in free state.
60 * The <type> argument defines the lock usage and is only used for debug.
61 * This type is actually stored in the associated busylock descriptor.
62 *******************************************************************************************
63 * @ lock   : local pointer on queuelock.
64 * @ type   : lock usage for debug.
65 ******************************************************************************************/
66inline void queuelock_init( queuelock_t * lock,
67                            uint32_t      type );
68
69/*******************************************************************************************
70 * This blocking function acquires a queuelock.
71 * The calling thread and the lock must be in same cluster.
72 * It uses the busylock to atomically access/update the queuelock state.
73 * If the lock is already taken, the calling thread atomically registers in the list
74 * of waiting threads (rooted in the lock descriptor), block and deschedule.
75 *******************************************************************************************
76 * @ lock   : local pointer on queuelock.
77 ******************************************************************************************/
78void queuelock_acquire( queuelock_t * lock );
79
80/*******************************************************************************************
81 * This function releases a queuelock.
82 * The calling thread and the lock must be in same cluster.
83 * It uses the busylock to atomically access/update the queuelock state.
84 * If the list of waiting threads is not empty, the first waiting thread is unblocked.
85 *******************************************************************************************
86 * @ lock   : local pointer on queuelock.
87 ******************************************************************************************/
88void queuelock_release( queuelock_t * lock );
89
90
91#endif  /* _QUEUELOCK_H_ */
Note: See TracBrowser for help on using the repository browser.