diff options
Diffstat (limited to 'static/freebsd/man9/rmlock.9 4.html')
| -rw-r--r-- | static/freebsd/man9/rmlock.9 4.html | 366 |
1 files changed, 0 insertions, 366 deletions
diff --git a/static/freebsd/man9/rmlock.9 4.html b/static/freebsd/man9/rmlock.9 4.html deleted file mode 100644 index 7120bb56..00000000 --- a/static/freebsd/man9/rmlock.9 4.html +++ /dev/null @@ -1,366 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">RMLOCK(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">RMLOCK(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">rmlock</code>, <code class="Nm">rm_init</code>, - <code class="Nm">rm_init_flags</code>, <code class="Nm">rm_destroy</code>, - <code class="Nm">rm_rlock</code>, <code class="Nm">rm_try_rlock</code>, - <code class="Nm">rm_wlock</code>, <code class="Nm">rm_runlock</code>, - <code class="Nm">rm_wunlock</code>, <code class="Nm">rm_wowned</code>, - <code class="Nm">rm_sleep</code>, <code class="Nm">rm_assert</code>, - <code class="Nm">RM_SYSINIT</code>, - <code class="Nm">RM_SYSINIT_FLAGS</code>, <code class="Nm">rms_init</code>, - <code class="Nm">rms_destroy</code>, <code class="Nm">rms_rlock</code>, - <code class="Nm">rms_wlock</code>, <code class="Nm">rms_runlock</code>, - <code class="Nm">rms_wunlock</code> — <span class="Nd">kernel - reader/writer lock optimized for read-mostly access patterns</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/param.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/lock.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/rmlock.h</a>></code></p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rm_init</code>(<var class="Fa" style="white-space: nowrap;">struct - rmlock *rm</var>, <var class="Fa" style="white-space: nowrap;">const char - *name</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rm_init_flags</code>(<var class="Fa" style="white-space: nowrap;">struct - rmlock *rm</var>, <var class="Fa" style="white-space: nowrap;">const char - *name</var>, <var class="Fa" style="white-space: nowrap;">int - opts</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rm_destroy</code>(<var class="Fa" style="white-space: nowrap;">struct - rmlock *rm</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rm_rlock</code>(<var class="Fa" style="white-space: nowrap;">struct - rmlock *rm</var>, <var class="Fa" style="white-space: nowrap;">struct - rm_priotracker* tracker</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">rm_try_rlock</code>(<var class="Fa" style="white-space: nowrap;">struct - rmlock *rm</var>, <var class="Fa" style="white-space: nowrap;">struct - rm_priotracker* tracker</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rm_wlock</code>(<var class="Fa" style="white-space: nowrap;">struct - rmlock *rm</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rm_runlock</code>(<var class="Fa" style="white-space: nowrap;">struct - rmlock *rm</var>, <var class="Fa" style="white-space: nowrap;">struct - rm_priotracker* tracker</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rm_wunlock</code>(<var class="Fa" style="white-space: nowrap;">struct - rmlock *rm</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">rm_wowned</code>(<var class="Fa" style="white-space: nowrap;">const - struct rmlock *rm</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">rm_sleep</code>(<var class="Fa" style="white-space: nowrap;">void - *wchan</var>, <var class="Fa" style="white-space: nowrap;">struct rmlock - *rm</var>, <var class="Fa" style="white-space: nowrap;">int priority</var>, - <var class="Fa" style="white-space: nowrap;">const char *wmesg</var>, - <var class="Fa" style="white-space: nowrap;">int timo</var>);</p> -<p class="Pp"> - <br/> - <code class="Cd">options INVARIANTS</code> - <br/> - <code class="Cd">options INVARIANT_SUPPORT</code> - <br/> - <var class="Ft">void</var> - <br/> - <code class="Fn">rm_assert</code>(<var class="Fa" style="white-space: nowrap;">struct - rmlock *rm</var>, <var class="Fa" style="white-space: nowrap;">int - what</var>);</p> -<p class="Pp"><code class="In">#include - <<a class="In">sys/kernel.h</a>></code></p> -<p class="Pp"><code class="Fn">RM_SYSINIT</code>(<var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">struct rmlock *rm</var>, - <var class="Fa" style="white-space: nowrap;">const char *desc</var>);</p> -<p class="Pp"><code class="Fn">RM_SYSINIT_FLAGS</code>(<var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">struct rmlock *rm</var>, - <var class="Fa" style="white-space: nowrap;">const char *desc</var>, - <var class="Fa" style="white-space: nowrap;">int flags</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rms_init</code>(<var class="Fa" style="white-space: nowrap;">struct - rmslock *rms</var>, <var class="Fa" style="white-space: nowrap;">const char - *name</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rms_destroy</code>(<var class="Fa" style="white-space: nowrap;">struct - rmslock *rms</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rms_rlock</code>(<var class="Fa" style="white-space: nowrap;">struct - rmslock *rms</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rms_wlock</code>(<var class="Fa" style="white-space: nowrap;">struct - rmslock *rms</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rms_runlock</code>(<var class="Fa" style="white-space: nowrap;">struct - rmslock *rms</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">rms_wunlock</code>(<var class="Fa" style="white-space: nowrap;">struct - rmslock *rms</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">Read-mostly locks allow shared access to protected data by - multiple threads, or exclusive access by a single thread. The threads with - shared access are known as - <a class="permalink" href="#readers"><i class="Em" id="readers">readers</i></a> - since they only read the protected data. A thread with exclusive access is - known as a - <a class="permalink" href="#writer"><i class="Em" id="writer">writer</i></a> - since it can modify protected data.</p> -<p class="Pp">Read-mostly locks are designed to be efficient for locks almost - exclusively used as reader locks and as such should be used for protecting - data that rarely changes. Acquiring an exclusive lock after the lock has - been locked for shared access is an expensive operation.</p> -<p class="Pp" id="rm_rlock">Normal read-mostly locks are similar to - <a class="Xr">rwlock(9)</a> locks and follow the same lock ordering rules as - <a class="Xr">rwlock(9)</a> locks. Read-mostly locks have full priority - propagation like mutexes. Unlike <a class="Xr">rwlock(9)</a>, read-mostly - locks propagate priority to both readers and writers. This is implemented - via the <var class="Va">rm_priotracker</var> structure argument supplied to - <a class="permalink" href="#rm_rlock"><code class="Fn">rm_rlock</code></a>() - and - <a class="permalink" href="#rm_runlock"><code class="Fn" id="rm_runlock">rm_runlock</code></a>(). - Readers can recurse if the lock is initialized with the - <code class="Dv">RM_RECURSE</code> option; however, writers are never - allowed to recurse.</p> -<p class="Pp" id="rm_init_flags">Sleeping for writers can be allowed by passing - <code class="Dv">RM_SLEEPABLE</code> to - <a class="permalink" href="#rm_init_flags"><code class="Fn">rm_init_flags</code></a>(). - It changes lock ordering rules to the same as for <a class="Xr">sx(9)</a> - locks. They do not propagate priority to writers, but they do propagate - priority to readers. Note that readers are not permitted to sleep regardless - of the flag.</p> -<p class="Pp" id="rms_init">Sleepable read-mostly locks (created with - <a class="permalink" href="#rms_init"><code class="Fn">rms_init</code></a>()) - allow sleeping for both readers and writers, but don't do priority - propagation for either. They follow <a class="Xr">sx(9)</a> lock - ordering.</p> -<section class="Ss"> -<h2 class="Ss" id="Macros_and_Functions"><a class="permalink" href="#Macros_and_Functions">Macros - and Functions</a></h2> -<dl class="Bl-tag"> - <dt id="rm_init"><a class="permalink" href="#rm_init"><code class="Fn">rm_init</code></a>(<var class="Fa">struct - rmlock *rm</var>, <var class="Fa">const char *name</var>)</dt> - <dd>Initialize the read-mostly lock <var class="Fa">rm</var>. The - <var class="Fa">name</var> description is used solely for debugging - purposes. This function must be called before any other operations on the - lock.</dd> - <dt><code class="Fn">rm_init_flags</code>(<var class="Fa">struct rmlock - *rm</var>, <var class="Fa">const char *name</var>, <var class="Fa">int - opts</var>)</dt> - <dd>Similar to <code class="Fn">rm_init</code>(), initialize the read-mostly - lock <var class="Fa">rm</var> with a set of optional flags. The - <var class="Fa">opts</var> arguments contains one or more of the following - flags: - <dl class="Bl-tag"> - <dt id="RM_NOWITNESS"><a class="permalink" href="#RM_NOWITNESS"><code class="Dv">RM_NOWITNESS</code></a></dt> - <dd>Instruct <a class="Xr">witness(4)</a> to ignore this lock.</dd> - <dt id="RM_RECURSE"><a class="permalink" href="#RM_RECURSE"><code class="Dv">RM_RECURSE</code></a></dt> - <dd>Allow threads to recursively acquire shared locks for - <var class="Fa">rm</var>.</dd> - <dt id="RM_SLEEPABLE"><a class="permalink" href="#RM_SLEEPABLE"><code class="Dv">RM_SLEEPABLE</code></a></dt> - <dd>Create a sleepable read-mostly lock.</dd> - <dt id="RM_NEW"><a class="permalink" href="#RM_NEW"><code class="Dv">RM_NEW</code></a></dt> - <dd>If the kernel has been compiled with <code class="Cd">option - INVARIANTS</code>, <code class="Fn">rm_init_flags</code>() will assert - that the <var class="Fa">rm</var> has not been initialized multiple - times without intervening calls to - <a class="permalink" href="#rm_destroy"><code class="Fn" id="rm_destroy">rm_destroy</code></a>() - unless this option is specified.</dd> - <dt id="RM_DUPOK"><a class="permalink" href="#RM_DUPOK"><code class="Dv">RM_DUPOK</code></a></dt> - <dd><a class="Xr">witness(4)</a> should not log messages about duplicate - locks being acquired.</dd> - </dl> - </dd> - <dt><code class="Fn">rm_rlock</code>(<var class="Fa">struct rmlock *rm</var>, - <var class="Fa">struct rm_priotracker* tracker</var>)</dt> - <dd>Lock <var class="Fa">rm</var> as a reader using - <var class="Fa">tracker</var> to track read owners of a lock for priority - propagation. This data structure is only used internally by - <code class="Nm">rmlock</code> and must persist until - <code class="Fn">rm_runlock</code>() has been called. This data structure - can be allocated on the stack since readers cannot sleep. If any thread - holds this lock exclusively, the current thread blocks, and its priority - is propagated to the exclusive holder. If the lock was initialized with - the <code class="Dv">RM_RECURSE</code> option the - <code class="Fn">rm_rlock</code>() function can be called when the current - thread has already acquired reader access on - <var class="Fa">rm</var>.</dd> - <dt id="rm_try_rlock"><a class="permalink" href="#rm_try_rlock"><code class="Fn">rm_try_rlock</code></a>(<var class="Fa">struct - rmlock *rm</var>, <var class="Fa">struct rm_priotracker* tracker</var>)</dt> - <dd>Try to lock <var class="Fa">rm</var> as a reader. - <code class="Fn">rm_try_rlock</code>() will return 0 if the lock cannot be - acquired immediately; otherwise, the lock will be acquired and a non-zero - value will be returned. Note that <code class="Fn">rm_try_rlock</code>() - may fail even while the lock is not currently held by a writer. If the - lock was initialized with the <code class="Dv">RM_RECURSE</code> option, - <code class="Fn">rm_try_rlock</code>() will succeed if the current thread - has already acquired reader access.</dd> - <dt id="rm_wlock"><a class="permalink" href="#rm_wlock"><code class="Fn">rm_wlock</code></a>(<var class="Fa">struct - rmlock *rm</var>)</dt> - <dd>Lock <var class="Fa">rm</var> as a writer. If there are any shared owners - of the lock, the current thread blocks. The - <code class="Fn">rm_wlock</code>() function cannot be called - recursively.</dd> - <dt><code class="Fn">rm_runlock</code>(<var class="Fa">struct rmlock - *rm</var>, <var class="Fa">struct rm_priotracker* tracker</var>)</dt> - <dd>This function releases a shared lock previously acquired by - <code class="Fn">rm_rlock</code>(). The <var class="Fa">tracker</var> - argument must match the <var class="Fa">tracker</var> argument used for - acquiring the shared lock</dd> - <dt id="rm_wunlock"><a class="permalink" href="#rm_wunlock"><code class="Fn">rm_wunlock</code></a>(<var class="Fa">struct - rmlock *rm</var>)</dt> - <dd>This function releases an exclusive lock previously acquired by - <code class="Fn">rm_wlock</code>().</dd> - <dt><code class="Fn">rm_destroy</code>(<var class="Fa">struct rmlock - *rm</var>)</dt> - <dd>This functions destroys a lock previously initialized with - <code class="Fn">rm_init</code>(). The <var class="Fa">rm</var> lock must - be unlocked.</dd> - <dt id="rm_wowned"><a class="permalink" href="#rm_wowned"><code class="Fn">rm_wowned</code></a>(<var class="Fa">const - struct rmlock *rm</var>)</dt> - <dd>This function returns a non-zero value if the current thread owns an - exclusive lock on <var class="Fa">rm</var>.</dd> - <dt id="rm_sleep"><a class="permalink" href="#rm_sleep"><code class="Fn">rm_sleep</code></a>(<var class="Fa">void - *wchan</var>, <var class="Fa">struct rmlock *rm</var>, <var class="Fa">int - priority</var>, <var class="Fa">const char *wmesg</var>, <var class="Fa">int - timo</var>)</dt> - <dd>This function atomically releases <var class="Fa">rm</var> while waiting - for an event. The <var class="Fa">rm</var> lock must be exclusively - locked. For more details on the parameters to this function, see - <a class="Xr">sleep(9)</a>.</dd> - <dt id="rm_assert"><a class="permalink" href="#rm_assert"><code class="Fn">rm_assert</code></a>(<var class="Fa">struct - rmlock *rm</var>, <var class="Fa">int what</var>)</dt> - <dd>This function asserts that the <var class="Fa">rm</var> lock is in the - state specified by <var class="Fa">what</var>. If the assertions are not - true and the kernel is compiled with <code class="Cd">options - INVARIANTS</code> and <code class="Cd">options INVARIANT_SUPPORT</code>, - the kernel will panic. Currently the following base assertions are - supported: - <dl class="Bl-tag"> - <dt id="RA_LOCKED"><a class="permalink" href="#RA_LOCKED"><code class="Dv">RA_LOCKED</code></a></dt> - <dd>Assert that current thread holds either a shared or exclusive lock of - <var class="Fa">rm</var>.</dd> - <dt id="RA_RLOCKED"><a class="permalink" href="#RA_RLOCKED"><code class="Dv">RA_RLOCKED</code></a></dt> - <dd>Assert that current thread holds a shared lock of - <var class="Fa">rm</var>.</dd> - <dt id="RA_WLOCKED"><a class="permalink" href="#RA_WLOCKED"><code class="Dv">RA_WLOCKED</code></a></dt> - <dd>Assert that current thread holds an exclusive lock of - <var class="Fa">rm</var>.</dd> - <dt id="RA_UNLOCKED"><a class="permalink" href="#RA_UNLOCKED"><code class="Dv">RA_UNLOCKED</code></a></dt> - <dd>Assert that current thread holds neither a shared nor exclusive lock - of <var class="Fa">rm</var>.</dd> - </dl> - <p class="Pp">In addition, one of the following optional flags may be - specified with <code class="Dv">RA_LOCKED</code>, - <code class="Dv">RA_RLOCKED</code>, or - <code class="Dv">RA_WLOCKED</code>:</p> - <dl class="Bl-tag"> - <dt id="RA_RECURSED"><a class="permalink" href="#RA_RECURSED"><code class="Dv">RA_RECURSED</code></a></dt> - <dd>Assert that the current thread holds a recursive lock of - <var class="Fa">rm</var>.</dd> - <dt id="RA_NOTRECURSED"><a class="permalink" href="#RA_NOTRECURSED"><code class="Dv">RA_NOTRECURSED</code></a></dt> - <dd>Assert that the current thread does not hold a recursive lock of - <var class="Fa">rm</var>.</dd> - </dl> - </dd> -</dl> -<dl class="Bl-tag"> - <dt id="rms_init~2"><a class="permalink" href="#rms_init~2"><code class="Fn">rms_init</code></a>(<var class="Fa">struct - rmslock *rms</var>, <var class="Fa">const char *name</var>)</dt> - <dd>Initialize the sleepable read-mostly lock <var class="Fa">rms</var>. The - <var class="Fa">name</var> description is used as - <var class="Fa">wmesg</var> parameter to the <a class="Xr">msleep(9)</a> - routine. This function must be called before any other operations on the - lock.</dd> - <dt id="rms_rlock"><a class="permalink" href="#rms_rlock"><code class="Fn">rms_rlock</code></a>(<var class="Fa">struct - rmlock *rm</var>)</dt> - <dd>Lock <var class="Fa">rms</var> as a reader. If any thread holds this lock - exclusively, the current thread blocks.</dd> - <dt id="rms_wlock"><a class="permalink" href="#rms_wlock"><code class="Fn">rms_wlock</code></a>(<var class="Fa">struct - rmslock *rms</var>)</dt> - <dd>Lock <var class="Fa">rms</var> as a writer. If the lock is already taken, - the current thread blocks. The <code class="Fn">rms_wlock</code>() - function cannot be called recursively.</dd> - <dt id="rms_runlock"><a class="permalink" href="#rms_runlock"><code class="Fn">rms_runlock</code></a>(<var class="Fa">struct - rmslock *rms</var>)</dt> - <dd>This function releases a shared lock previously acquired by - <code class="Fn">rms_rlock</code>().</dd> - <dt id="rms_wunlock"><a class="permalink" href="#rms_wunlock"><code class="Fn">rms_wunlock</code></a>(<var class="Fa">struct - rmslock *rms</var>)</dt> - <dd>This function releases an exclusive lock previously acquired by - <code class="Fn">rms_wlock</code>().</dd> - <dt id="rms_destroy"><a class="permalink" href="#rms_destroy"><code class="Fn">rms_destroy</code></a>(<var class="Fa">struct - rmslock *rms</var>)</dt> - <dd>This functions destroys a lock previously initialized with - <code class="Fn">rms_init</code>(). The <var class="Fa">rms</var> lock - must be unlocked.</dd> -</dl> -</section> -</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">locking(9)</a>, <a class="Xr">mutex(9)</a>, - <a class="Xr">panic(9)</a>, <a class="Xr">rwlock(9)</a>, - <a class="Xr">sema(9)</a>, <a class="Xr">sleep(9)</a>, - <a class="Xr">sx(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">These functions appeared in <span class="Ux">FreeBSD - 7.0</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">The <code class="Nm">rmlock</code> facility was written by - <span class="An">Stephan Uphoff</span>. This manual page was written by - <span class="An">Gleb Smirnoff</span> for rwlock and modified to reflect - rmlock by <span class="An">Stephan Uphoff</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> -<p class="Pp">The <code class="Nm">rmlock</code> implementation is currently not - optimized for single processor systems.</p> -<p class="Pp"><code class="Fn">rm_try_rlock</code>() can fail transiently even - when there is no writer, while another reader updates the state on the local - CPU.</p> -<p class="Pp">The <code class="Nm">rmlock</code> implementation uses a single - per CPU list shared by all rmlocks in the system. If rmlocks become popular, - hashing to multiple per CPU queues may be needed to speed up the writer lock - process.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">April 12, 2021</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |