3 <meta name="generator" content="groff -Thtml, see www.gnu.org">
4 <meta name="Content-Style" content="text/css">
5 <title>new_rwlock</title>
9 <h1 align=center>new_rwlock</h1>
10 <a href="#NAME">NAME</a><br>
11 <a href="#SYNOPSIS">SYNOPSIS</a><br>
12 <a href="#DESCRIPTION">DESCRIPTION</a><br>
13 <a href="#BUGS">BUGS</a><br>
14 <a href="#AUTHOR">AUTHOR</a><br>
15 <a href="#LICENSE">LICENSE</a><br>
16 <a href="#VERSION">VERSION</a><br>
19 <!-- Creator : groff version 1.17.2 -->
20 <!-- CreationDate: Fri Aug 30 16:16:43 2002 -->
23 <table width="100%" border=0 rules="none" frame="void"
24 cols="2" cellspacing="0" cellpadding="0">
25 <tr valign="top" align="left">
26 <td width="10%"></td><td width="90%">
27 new_rwlock, rwlock_writers_have_priority, rwlock_readers_have_priority, rwlock_enter_read, rwlock_enter_write, rwlock_try_enter_read, rwlock_try_enter_write, rwlock_leave - multiple reader / single writer locks (rwlocks)</td></table>
28 <a name="SYNOPSIS"></a>
31 <table width="100%" border=0 rules="none" frame="void"
32 cols="2" cellspacing="0" cellpadding="0">
33 <tr valign="top" align="left">
34 <td width="10%"></td><td width="90%">
35 <pre><b>#include <pthr_rwlock.h>
37 rwlock new_rwlock (pool);
38 void rwlock_writers_have_priority (rwlock);
39 void rwlock_readers_have_priority (rwlock);
40 void rwlock_enter_read (rwlock, pseudothread);
41 void rwlock_enter_write (rwlock, pseudothread);
42 int rwlock_try_enter_read (rwlock, pseudothread);
43 int rwlock_try_enter_write (rwlock, pseudothread);
44 void rwlock_leave (rwlock, pseudothread);
45 </b></pre></td></table>
46 <a name="DESCRIPTION"></a>
49 <table width="100%" border=0 rules="none" frame="void"
50 cols="2" cellspacing="0" cellpadding="0">
51 <tr valign="top" align="left">
52 <td width="10%"></td><td width="90%">
53 Multiple reader / single writer locks (rwlocks) do what they
54 say. They allow either many readers to access a critical
55 section or a single writer (but not both). If instead you
56 require simple mutex semantics, then please see
57 <pthr_mutex.h>.</td></table>
59 <table width="100%" border=0 rules="none" frame="void"
60 cols="2" cellspacing="0" cellpadding="0">
61 <tr valign="top" align="left">
62 <td width="10%"></td><td width="90%">
63 RWlocks are automatically released if they are being held
64 when the thread exits.</td></table>
66 <table width="100%" border=0 rules="none" frame="void"
67 cols="2" cellspacing="0" cellpadding="0">
68 <tr valign="top" align="left">
69 <td width="10%"></td><td width="90%">
70 RWlocks are not ``upgradable''. The implementation is too
71 complex to justify that.</td></table>
73 <table width="100%" border=0 rules="none" frame="void"
74 cols="2" cellspacing="0" cellpadding="0">
75 <tr valign="top" align="left">
76 <td width="10%"></td><td width="90%">
77 Note that there are possible deadlocks when using locks. To
78 avoid deadlocks, always ensure every thread acquires locks
79 in the same order.</td></table>
81 <table width="100%" border=0 rules="none" frame="void"
82 cols="2" cellspacing="0" cellpadding="0">
83 <tr valign="top" align="left">
84 <td width="10%"></td><td width="90%">
85 <b>new_rwlock</b> creates a new rwlock object.</td></table>
87 <table width="100%" border=0 rules="none" frame="void"
88 cols="2" cellspacing="0" cellpadding="0">
89 <tr valign="top" align="left">
90 <td width="10%"></td><td width="90%">
91 <b>rwlock_writers_have_priority</b> changes the nature of
92 the lock so that writers have priority over readers. If this
93 is the case then new readers will not be able to enter a
94 critical section if there are writers waiting to enter. [NB:
95 This is the default.]</td></table>
97 <table width="100%" border=0 rules="none" frame="void"
98 cols="2" cellspacing="0" cellpadding="0">
99 <tr valign="top" align="left">
100 <td width="10%"></td><td width="90%">
101 <b>rwlock_readers_have_priority</b> changes the nature of
102 the lock so that readers have priority over writers. Note
103 that if this is the case then writers are likely to be
104 starved if the lock is frequently read.</td></table>
106 <table width="100%" border=0 rules="none" frame="void"
107 cols="2" cellspacing="0" cellpadding="0">
108 <tr valign="top" align="left">
109 <td width="10%"></td><td width="90%">
110 <b>rwlock_enter_read</b> enters the critical section as a
111 reader. Any number of readers are allowed to enter a
112 critical section at the same time. This function may
115 <table width="100%" border=0 rules="none" frame="void"
116 cols="2" cellspacing="0" cellpadding="0">
117 <tr valign="top" align="left">
118 <td width="10%"></td><td width="90%">
119 <b>rwlock_enter_write</b> enters the critical section as a
120 writer. Only a single writer is allowed to enter a critical
121 section, and then only if there are no readers. This
122 function may block.</td></table>
124 <table width="100%" border=0 rules="none" frame="void"
125 cols="2" cellspacing="0" cellpadding="0">
126 <tr valign="top" align="left">
127 <td width="10%"></td><td width="90%">
128 <b>rwlock_try_enter_read</b> is identical to
129 <b>rwlock_enter_read</b>, but it does not block. It returns
130 true if the lock was successfully acquired, or false if the
131 operation would block.</td></table>
133 <table width="100%" border=0 rules="none" frame="void"
134 cols="2" cellspacing="0" cellpadding="0">
135 <tr valign="top" align="left">
136 <td width="10%"></td><td width="90%">
137 <b>rwlock_try_enter_write</b> is identical to
138 <b>rwlock_enter_write</b>, but it does not block. It returns
139 true if the lock was successfully acquired, or false if the
140 operation would block.</td></table>
142 <table width="100%" border=0 rules="none" frame="void"
143 cols="2" cellspacing="0" cellpadding="0">
144 <tr valign="top" align="left">
145 <td width="10%"></td><td width="90%">
146 <b>rwlock_leave</b> leaves the critical
147 section.</td></table>
151 <table width="100%" border=0 rules="none" frame="void"
152 cols="2" cellspacing="0" cellpadding="0">
153 <tr valign="top" align="left">
154 <td width="10%"></td><td width="90%">
155 A common mistake is to accidentally call <b>rwlock_leave</b>
156 when you are not holding the lock. This generally causes the
157 library to crash.</td></table>
158 <a name="AUTHOR"></a>
161 <table width="100%" border=0 rules="none" frame="void"
162 cols="2" cellspacing="0" cellpadding="0">
163 <tr valign="top" align="left">
164 <td width="10%"></td><td width="90%">
165 Richard Jones <rich@annexia.org></td></table>
166 <a name="LICENSE"></a>
169 <table width="100%" border=0 rules="none" frame="void"
170 cols="2" cellspacing="0" cellpadding="0">
171 <tr valign="top" align="left">
172 <td width="10%"></td><td width="90%">
173 GNU LGPL (see http://www.gnu.org/)</td></table>
174 <a name="VERSION"></a>
177 <table width="100%" border=0 rules="none" frame="void"
178 cols="2" cellspacing="0" cellpadding="0">
179 <tr valign="top" align="left">
180 <td width="10%"></td><td width="90%">
181 pthrlib-3.0.3</td></table>