1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
/*
* The MIT License
*
* Copyright (C) 2016 Alexander Saprykin <saprykin.spb@gmail.com>
*
* Permission is hereby granted, free of charge, to any person obtaining
* a copy of this software and associated documentation files (the
* 'Software'), to deal in the Software without restriction, including
* without limitation the rights to use, copy, modify, merge, publish,
* distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so, subject to
* the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
/**
* @file prwlock.h
* @brief Read-write lock
* @author Alexander Saprykin
*
* A read-write lock is a synchronization primitive which allows access to a
* critical section to not only the one thread, but instead it splits all
* threads into the two groups:
* - reader threads which perform only the reading operations without any shared
* data modifications;
* - writer threads which may perform the shared data modifitcations as well as
* its reading.
*
* When there are only the reader threads inside a critical section it is called
* a shared lock - actually you do not need any locking mechanism and all the
* threads share the lock. In this situation an arbitrary number of reader
* threads can perform shared data reading.
*
* The situation changes when a writer thread requests access to the same
* critical section. It will wait until all the current readers finish
* executing the critical section before acquiring the lock in exclusive manner:
* no one else can access the critical section until the writer finishes with
* it. Even another writer thread will have to wait for the lock to be released
* by the first writer before entering the critical section.
*
* To prevent writer startvation usually writers are in favor over readers,
* which is actually implementation dependent, though most operating systems try
* to follow this rule.
*
* A read-write lock is usually used when the writing operations are not
* performed too frequently, or when the number of reader threads is a way more
* than writer ones.
*
* A reader enters a critical section with p_rwlock_reader_lock() or
* p_rwlock_reader_trylock() and exits with p_rwlock_reader_unlock().
*
* A writer enters the critical section with p_rwlock_writer_lock() or
* p_rwlock_writer_trylock() and exits with p_rwlock_writer_unlock().
*/
#if !defined (PLIBSYS_H_INSIDE) && !defined (PLIBSYS_COMPILATION)
# error "Header files shouldn't be included directly, consider using <plibsys.h> instead."
#endif
#ifndef PLIBSYS_HEADER_PRWLOCK_H
#define PLIBSYS_HEADER_PRWLOCK_H
#include <pmacros.h>
#include <ptypes.h>
P_BEGIN_DECLS
/** Read-write lock opaque data structure. */
typedef struct PRWLock_ PRWLock;
/**
* @brief Creates a new #PRWLock object.
* @return Pointer to a newly created #PRWLock object.
* @since 0.0.1
*/
P_LIB_API PRWLock * p_rwlock_new (void);
/**
* @brief Locks a read-write lock for reading.
* @param lock #PRWLock to lock.
* @return TRUE in case of success, FALSE otherwise.
* @since 0.0.1
* @warning Do not lock a read-write lock recursively - it may lead to an
* application deadlock (implementation dependent).
*
* Forces the calling thread to sleep until the @a lock becomes available for
* locking.
*/
P_LIB_API pboolean p_rwlock_reader_lock (PRWLock *lock);
/**
* @brief Tries to lock a read-write lock for reading immediately.
* @param lock #PRWLock to lock.
* @return TRUE in case of success, FALSE otherwise.
* @since 0.0.1
* @warning Do not lock a read-write lock recursively - it may lead to an
* application deadlock (implementation dependent).
*
* Tries to lock the @a lock and returns immediately if it is not available for
* locking.
*/
P_LIB_API pboolean p_rwlock_reader_trylock (PRWLock *lock);
/**
* @brief Releases a locked for reading read-write lock.
* @param lock #PRWLock to release.
* @return TRUE in case of success, FALSE otherwise.
* @since 0.0.1
* @warning Do not use this function on non-locked read-write locks - behavior
* may be unpredictable.
* @warning Do not use this function to unlock a read-write lock which was
* locked for writing.
*
* If the @a lock was previously locked for reading then it becomes unlocked.
*
* It's implementation dependent whether only the same thread can lock and
* unlock the same read-write lock.
*/
P_LIB_API pboolean p_rwlock_reader_unlock (PRWLock *lock);
/**
* @brief Locks a read-write lock for writing.
* @param lock #PRWLock to lock.
* @return TRUE in case of success, FALSE otherwise.
* @since 0.0.1
* @warning Do not lock a read-write lock recursively - it may lead to an
* application deadlock (implementation dependent).
*
* Forces the calling thread to sleep until the @a lock becomes available for
* locking.
*/
P_LIB_API pboolean p_rwlock_writer_lock (PRWLock *lock);
/**
* @brief Tries to lock a read-write lock immediately.
* @param lock #PRWLock to lock.
* @return TRUE in case of success, FALSE otherwise.
* @since 0.0.1
* @warning Do not lock a read-write lock recursively - it may lead to an
* application deadlock (implementation dependent).
*
* Tries to lock the @a lock and returns immediately if it is not available for
* locking.
*/
P_LIB_API pboolean p_rwlock_writer_trylock (PRWLock *lock);
/**
* @brief Releases a locked for writing read-write lock.
* @param lock #PRWLock to release.
* @return TRUE in case of success, FALSE otherwise.
* @since 0.0.1
* @warning Do not use this function on non-locked read-write locks - behavior
* may be unpredictable.
* @warning Do not use this function to unlock a read-write lock which was
* locked for reading.
*
* If the @a lock was previously locked for writing then it becomes unlocked.
*
* It's implementation dependent whether only the same thread can lock and
* unlock the same read-write lock.
*/
P_LIB_API pboolean p_rwlock_writer_unlock (PRWLock *lock);
/**
* @brief Frees a #PRWLock object.
* @param lock #PRWLock to free.
* @since 0.0.1
* @warning It doesn't unlock the @a lock before freeing memory, so you should
* do it manually.
*/
P_LIB_API void p_rwlock_free (PRWLock *lock);
P_END_DECLS
#endif /* PLIBSYS_HEADER_PRWLOCK_H */
|
