doc/new_rwlock.3.html

   1 <html>
   2 <head>
   3 <meta name="generator" content="groff -Thtml, see www.gnu.org">
   4 <meta name="Content-Style" content="text/css">
   5 <title>new_rwlock</title>
   6 </head>
   7 <body>
   8
   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>
  17
  18 <hr>
  19 <!-- Creator     : groff version 1.17.2 -->
  20 <!-- CreationDate: Fri Aug 30 16:16:31 2002 -->
  21 <a name="NAME"></a>
  22 <h2>NAME</h2>
  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>
  29 <h2>SYNOPSIS</h2>
  30
  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 &lt;pthr_rwlock.h&gt;
  36
  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>
  47 <h2>DESCRIPTION</h2>
  48
  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 &lt;pthr_mutex.h&gt;.</td></table>
  58
  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>
  65
  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>
  72
  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>
  80
  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>
  86
  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>
  96
  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>
 105
 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
 113 block.</td></table>
 114
 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>
 123
 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>
 132
 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>
 141
 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>
 148 <a name="BUGS"></a>
 149 <h2>BUGS</h2>
 150
 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>
 159 <h2>AUTHOR</h2>
 160
 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 &lt;rich@annexia.org&gt;</td></table>
 166 <a name="LICENSE"></a>
 167 <h2>LICENSE</h2>
 168
 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>
 175 <h2>VERSION</h2>
 176
 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>
 182 <hr>
 183 </body>
 184 </html>