1 /* Multiple reader / single writer locks for pthrlib.
2 * by Richard W.M. Jones <rich@annexia.org>
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the Free
16 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18 * $Id: pthr_rwlock.h,v 1.3 2002/12/01 14:29:30 rich Exp $
27 #include "pthr_pseudothread.h"
28 #include "pthr_wait_queue.h"
31 typedef struct rwlock *rwlock;
33 /* Function: new_rwlock - multiple reader / single writer locks (rwlocks)
34 * Function: rwlock_writers_have_priority
35 * Function: rwlock_readers_have_priority
36 * Function: rwlock_enter_read
37 * Function: rwlock_enter_write
38 * Function: rwlock_try_enter_read
39 * Function: rwlock_try_enter_write
40 * Function: rwlock_leave
42 * Multiple reader / single writer locks (rwlocks) do what they
43 * say. They allow either many readers to access a critical section
44 * or a single writer (but not both). If instead you require simple
45 * mutex semantics, then please see <pthr_mutex.h>.
47 * RWlocks are automatically released if they are being held when
50 * RWlocks are not ``upgradable''. The implementation is too
51 * complex to justify that.
53 * Note that there are possible deadlocks when using locks. To
54 * avoid deadlocks, always ensure every thread acquires locks
57 * @code{new_rwlock} creates a new rwlock object.
59 * @code{rwlock_writers_have_priority} changes the nature of the lock so that
60 * writers have priority over readers. If this is the case then
61 * new readers will not be able to enter a critical section if
62 * there are writers waiting to enter.
63 * [NB: This is the default.]
65 * @code{rwlock_readers_have_priority} changes the nature of the lock so that
66 * readers have priority over writers. Note that if this is the case
67 * then writers are likely to be starved if the lock is frequently
70 * @code{rwlock_enter_read} enters the critical section as a reader.
71 * Any number of readers are allowed to enter a critical section at
72 * the same time. This function may block.
74 * @code{rwlock_enter_write} enters the critical section as a writer.
75 * Only a single writer is allowed to enter a critical section, and
76 * then only if there are no readers. This function may block.
78 * @code{rwlock_try_enter_read} is identical to
79 * @code{rwlock_enter_read}, but it
80 * does not block. It returns true if the lock was successfully
81 * acquired, or false if the operation would block.
83 * @code{rwlock_try_enter_write} is identical to
84 * @code{rwlock_enter_write}, but it
85 * does not block. It returns true if the lock was successfully
86 * acquired, or false if the operation would block.
88 * @code{rwlock_leave} leaves the critical section.
90 * Bugs: A common mistake is to accidentally call @code{rwlock_leave}
91 * when you are not holding the lock. This generally causes the
94 extern rwlock new_rwlock (pool);
95 extern void rwlock_writers_have_priority (rwlock);
96 extern void rwlock_readers_have_priority (rwlock);
97 extern void rwlock_enter_read (rwlock);
98 extern void rwlock_enter_write (rwlock);
99 extern int rwlock_try_enter_read (rwlock);
100 extern int rwlock_try_enter_write (rwlock);
101 extern void rwlock_leave (rwlock);
103 #endif /* PTHR_RWLOCK_H */