source: trunk/kernel/libk/rwlock.h @ 687

Last change on this file since 687 was 563, checked in by alain, 6 years ago

Complete restructuration of kernel spinlocks.

File size: 5.3 KB
Line 
1/*
2 * rwlock.h - kernel local read/write lock definition.
3 *
4 * Author   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 _RWLOCK_H_
25#define _RWLOCK_H_
26
27#include <kernel_config.h>
28#include <hal_kernel_types.h>
29#include <busylock.h>
30#include <list.h>
31
32/******************************************************************************************n
33 * This structure defines a kernel, local, read/write lock, supporting several simultaneous
34 * read accesses, but only one write access to a given locally shared object in a cluster.
35 * Both readers and writers take the associated busylock before accessing or updating
36 * the rwlock state, and releases the busylock after rwlock state update.
37 * - when a reader try to access the object, it increments the readers "count" when the
38 *   lock is not "taken" by a writer. It registers in the "rd_root" waiting queue, blocks,
39 *   and deschedules when the lock is taken.
40 * - when a writer try to take the rwlock, it check the "taken" field. If the lock is already
41 *   taken, or if the number of readers is non zero, it registers in the "wr_root" waiting
42 *   queue, blocks, and deschedules. It set "taken" otherwise.
43 * - when a reader completes its access, it decrement the readers "count", unblock the
44 *   the first waiting writer if there is no other readers, and unblock all waiting
45 *   readers if there no write request.
46 * - when a  writer completes its access, it reset the "taken" field, releases the first
47 *   waiting writer if queue non empty, or releases all waiting readers if no writer.
48 ******************************************************************************************/
49
50/*******************************************************************************************
51 * This structure defines a local rwlock.
52 ******************************************************************************************/
53
54typedef struct rwlock_s
55{
56    busylock_t          lock;        /*! busylock protecting the rwlock state             */
57        volatile uint32_t   taken;       /*! lock taken by an exclusive writer if non zero    */
58    volatile uint32_t   count;       /*! current number of simultaneous readers threads   */
59    list_entry_t        rd_root;     /*! root of list of waiting readers                  */
60    list_entry_t        wr_root;     /*! root of list of waiting writers                  */
61}
62rwlock_t;
63
64/*******************************************************************************************
65 * This function initializes a local rwlock.
66 * The <type> argument defines the lock usage and is only used for debug.
67 * This type is actually stored in the associated busylock descriptor.
68 *******************************************************************************************
69 * @ lock       : pointer on rwlock.
70 * @ type       : lock usage for debug.
71 ******************************************************************************************/
72void rwlock_init( rwlock_t * lock,
73                  uint32_t   type );
74
75/*******************************************************************************************
76 * This function get access to a local rwlock for a reader.
77 *******************************************************************************************
78 * @ lock       : pointer on rwlock
79 ******************************************************************************************/
80void rwlock_rd_acquire( rwlock_t * lock );
81
82/*******************************************************************************************
83 * This function get access to a local rwlock for a writer.
84 *******************************************************************************************
85 * @ lock       : pointer on rwlock
86 ******************************************************************************************/
87void rwlock_wr_acquire( rwlock_t * lock );
88
89/*******************************************************************************************
90 * This function unlocks a local rwlock for a reader.
91 *******************************************************************************************
92 * @ lock       : pointer on rwlock
93 ******************************************************************************************/
94void rwlock_rd_release( rwlock_t * lock );
95
96/*******************************************************************************************
97 * This function unlocks a local rwlock for a writer.
98 *******************************************************************************************
99 * @ lock       : pointer on rwlock
100 ******************************************************************************************/
101void rwlock_wr_release( rwlock_t * lock );
102
103
104#endif  /* _RWLOCK_H_ */
Note: See TracBrowser for help on using the repository browser.