diff options
Diffstat (limited to 'static/netbsd/man9/rwlock.9 3.html')
| -rw-r--r-- | static/netbsd/man9/rwlock.9 3.html | 256 |
1 files changed, 0 insertions, 256 deletions
diff --git a/static/netbsd/man9/rwlock.9 3.html b/static/netbsd/man9/rwlock.9 3.html deleted file mode 100644 index 239ed9ad..00000000 --- a/static/netbsd/man9/rwlock.9 3.html +++ /dev/null @@ -1,256 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">RWLOCK(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">RWLOCK(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">rw</code>, <code class="Nm">rw_init</code>, - <code class="Nm">rw_destroy</code>, <code class="Nm">rw_enter</code>, - <code class="Nm">rw_exit</code>, <code class="Nm">rw_tryenter</code>, - <code class="Nm">rw_tryupgrade</code>, <code class="Nm">rw_downgrade</code>, - <code class="Nm">rw_read_held</code>, <code class="Nm">rw_write_held</code>, - <code class="Nm">rw_lock_held</code>, <code class="Nm">rw_lock_op</code> - — <span class="Nd">reader / writer lock primitives</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/rwlock.h</a>></code></p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rw_init</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t - *rw</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rw_destroy</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t - *rw</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rw_enter</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t - *rw</var>, <var class="Fa" style="white-space: nowrap;">const krw_t - op</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rw_exit</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t - *rw</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">rw_tryenter</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t - *rw</var>, <var class="Fa" style="white-space: nowrap;">const krw_t - op</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">rw_tryupgrade</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t - *rw</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rw_downgrade</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t - *rw</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">rw_read_held</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t - *rw</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">rw_write_held</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t - *rw</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">rw_lock_held</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t - *rw</var>);</p> -<p class="Pp"><var class="Ft">krw_t</var> - <br/> - <code class="Fn">rw_lock_op</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t - *rw</var>);</p> -<p class="Pp"> - <br/> - <code class="Cd">options DIAGNOSTIC</code> - <br/> - <code class="Cd">options LOCKDEBUG</code></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">Reader / writer locks (RW locks) are used in the kernel to - synchronize access to an object among LWPs (lightweight processes) and soft - interrupt handlers.</p> -<p class="Pp">In addition to the capabilities provided by mutexes, RW locks - distinguish between read (shared) and write (exclusive) access.</p> -<p class="Pp">RW locks are in one of three distinct states at any given - time:</p> -<dl class="Bl-tag"> - <dt id="Unlocked"><a class="permalink" href="#Unlocked"><code class="Dv">Unlocked</code></a></dt> - <dd>The lock is not held.</dd> - <dt id="Read"><a class="permalink" href="#Read"><code class="Dv">Read - locked</code></a></dt> - <dd>The lock holders intend to read the protected object. Multiple callers may - hold a RW lock with “read intent” simultaneously.</dd> - <dt id="Write"><a class="permalink" href="#Write"><code class="Dv">Write - locked</code></a></dt> - <dd>The lock holder intends to update the protected object. Only one caller - may hold a RW lock with “write intent”.</dd> -</dl> -<p class="Pp">The <var class="Vt">krwlock_t</var> type provides storage for the - RW lock object. This should be treated as an opaque object and not examined - directly by consumers.</p> -<p class="Pp">Note that these interfaces must not be used from a hardware - interrupt handler.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="OPTIONS_AND_MACROS"><a class="permalink" href="#OPTIONS_AND_MACROS">OPTIONS - AND MACROS</a></h1> -<dl class="Bl-tag"> - <dt><code class="Cd">options DIAGNOSTIC</code></dt> - <dd> - <p class="Pp">Kernels compiled with the <code class="Dv">DIAGNOSTIC</code> - option perform basic sanity checks on RW lock operations.</p> - </dd> - <dt><code class="Cd">options LOCKDEBUG</code></dt> - <dd> - <p class="Pp">Kernels compiled with the <code class="Dv">LOCKDEBUG</code> - option perform potentially CPU intensive sanity checks on RW lock - operations.</p> - </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> -<dl class="Bl-tag"> - <dt id="rw_init"><a class="permalink" href="#rw_init"><code class="Fn">rw_init</code></a>(<var class="Fa">rw</var>)</dt> - <dd> - <p class="Pp">Initialize a lock for use. No other operations can be - performed on the lock until it has been initialized.</p> - </dd> - <dt id="rw_destroy"><a class="permalink" href="#rw_destroy"><code class="Fn">rw_destroy</code></a>(<var class="Fa">rw</var>)</dt> - <dd> - <p class="Pp">Release resources used by a lock. The lock may not be used - after it has been destroyed.</p> - </dd> - <dt id="rw_enter"><a class="permalink" href="#rw_enter"><code class="Fn">rw_enter</code></a>(<var class="Fa">rw</var>, - <var class="Fa">op</var>)</dt> - <dd> - <p class="Pp">If <code class="Dv">RW_READER</code> is specified as the - argument to <var class="Fa">op</var>, acquire a read lock. The caller - may block and will not return until the hold is acquired. Callers must - not recursively acquire read locks.</p> - <p class="Pp">If <code class="Dv">RW_WRITER</code> is specified, acquire a - write lock. If the lock is already held, the caller will block and not - return until the hold is acquired.</p> - <p class="Pp">RW locks and other types of locks must always be acquired in a - consistent order with respect to each other. Otherwise, the potential - for system deadlock exists.</p> - </dd> - <dt id="rw_exit"><a class="permalink" href="#rw_exit"><code class="Fn">rw_exit</code></a>(<var class="Fa">rw</var>)</dt> - <dd> - <p class="Pp">Release a lock. The lock must have been previously acquired by - the caller.</p> - </dd> - <dt id="rw_tryenter"><a class="permalink" href="#rw_tryenter"><code class="Fn">rw_tryenter</code></a>(<var class="Fa">rw</var>, - <var class="Fa">op</var>)</dt> - <dd> - <p class="Pp">Try to acquire a lock, but do not block if the lock is already - held. If the lock is acquired successfully, return non-zero. Otherwise, - return zero.</p> - <p class="Pp">Valid arguments to <var class="Fa">op</var> are - <code class="Dv">RW_READER</code> or - <code class="Dv">RW_WRITER</code>.</p> - </dd> - <dt id="rw_tryupgrade"><a class="permalink" href="#rw_tryupgrade"><code class="Fn">rw_tryupgrade</code></a>(<var class="Fa">rw</var>)</dt> - <dd> - <p class="Pp">Try to upgrade a lock from one read hold to a write hold. If - the lock is upgraded successfully, returns non-zero. Otherwise, returns - zero.</p> - </dd> - <dt id="rw_downgrade"><a class="permalink" href="#rw_downgrade"><code class="Fn">rw_downgrade</code></a>(<var class="Fa">rw</var>)</dt> - <dd> - <p class="Pp">Downgrade a lock from a write hold to a read hold.</p> - </dd> - <dt id="rw_write_held"><a class="permalink" href="#rw_write_held"><code class="Fn">rw_write_held</code></a>(<var class="Fa">rw</var>)</dt> - <dd> - <p class="Pp">Return non-zero if write lock is held by current lwp. - Otherwise, return zero.</p> - </dd> - <dt id="rw_read_held"><a class="permalink" href="#rw_read_held"><code class="Fn">rw_read_held</code></a>(<var class="Fa">rw</var>)</dt> - <dd> - <p class="Pp">Returns non-zero if read lock is held by any lwp. Otherwise, - return zero.</p> - </dd> - <dt id="rw_lock_held"><a class="permalink" href="#rw_lock_held"><code class="Fn">rw_lock_held</code></a>(<var class="Fa">rw</var>)</dt> - <dd> - <p class="Pp">Returns non-zero if either read or write lock is held by any - lwp. Otherwise, return zero.</p> - <p class="Pp" id="rw_write_held~2"><a class="permalink" href="#rw_write_held~2"><code class="Fn">rw_write_held</code></a>(), - <code class="Fn">rw_read_held</code>(), and - <code class="Fn">rw_lock_held</code>() should not generally be used to - make locking decisions at run time: they are provided for diagnostic - purposes, for example making assertions.</p> - <p class="Pp" id="rw_write_held~3">Negative assertions (lock not held) - should not be made due to atomicity issues, excepting - <a class="permalink" href="#rw_write_held~3"><code class="Fn">rw_write_held</code></a>(), - which can safely be used to assert that a write lock is NOT held by the - current LWP.</p> - </dd> - <dt id="rw_lock_op"><a class="permalink" href="#rw_lock_op"><code class="Fn">rw_lock_op</code></a>(<var class="Fa">rw</var>)</dt> - <dd> - <p class="Pp">For a lock that is known to be held by the calling LWP, return - either <code class="Dv">RW_READER</code> or - <code class="Dv">RW_WRITER</code> to denote the type of hold. This is - useful when dropping and later re-acquiring a lock, if the type of hold - is not already known.</p> - </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="PERFORMANCE_CONSIDERATIONS"><a class="permalink" href="#PERFORMANCE_CONSIDERATIONS">PERFORMANCE - CONSIDERATIONS</a></h1> -<p class="Pp">RW locks are subject to high cache contention on multiprocessor - systems, and scale poorly when the write:read ratio is not strongly in - favour of readers. Ideally, RW locks should only be used in settings when - the following three conditions are met:</p> -<ul class="Bl-bullet"> - <li>The data object(s) protected by the RW lock are read much more frequently - than written.</li> - <li>The read-side hold time for the RW lock is long (in the order of thousands - of processor clock cycles).</li> - <li>Strong synchronization semantics are required: there is no scope for - lockless, lazy or optimistic synchronization.</li> -</ul> -<p class="Pp">Generally speaking, it is better to organise code paths and/or - data flows such that fewer and weaker synchronization points are required to - ensure correct operation.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE - REFERENCES</a></h1> -<p class="Pp">The core of the RW lock implementation is in - <span class="Pa">sys/kern/kern_rwlock.c</span>.</p> -<p class="Pp">The header file <span class="Pa">sys/sys/rwlock.h</span> describes - the public interface, and interfaces that machine-dependent code must - provide to support RW locks.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">membar_ops(3)</a>, <a class="Xr">lockstat(8)</a>, - <a class="Xr">condvar(9)</a>, <a class="Xr">mutex(9)</a></p> -<p class="Pp"><cite class="Rs"><span class="RsA">Jim Mauro</span> and - <span class="RsA">Richard McDougall</span>, <span class="RsT">Solaris - Internals: Core Kernel Architecture</span>, <i class="RsI">Prentice - Hall</i>, <span class="RsD">2001</span>, <span class="RsO">ISBN - 0-13-022496-0</span>.</cite></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The RW lock primitives first appeared in <span class="Ux">NetBSD - 5.0</span>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">February 22, 2020</td> - <td class="foot-os">NetBSD 10.1</td> - </tr> -</table> |