diff options
Diffstat (limited to 'static/netbsd/man9/localcount.9 3.html')
| -rw-r--r-- | static/netbsd/man9/localcount.9 3.html | 170 |
1 files changed, 0 insertions, 170 deletions
diff --git a/static/netbsd/man9/localcount.9 3.html b/static/netbsd/man9/localcount.9 3.html deleted file mode 100644 index d71eac71..00000000 --- a/static/netbsd/man9/localcount.9 3.html +++ /dev/null @@ -1,170 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">LOCALCOUNT(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">LOCALCOUNT(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">localcount</code>, - <code class="Nm">localcount_init</code>, - <code class="Nm">localcount_fini</code>, - <code class="Nm">localcount_acquire</code>, - <code class="Nm">localcount_release</code>, - <code class="Nm">localcount_drain</code> — - <span class="Nd">reference-count 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/localcount.h</a>></code></p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">localcount_init</code>(<var class="Fa" style="white-space: nowrap;">struct - localcount *lc</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">localcount_fini</code>(<var class="Fa" style="white-space: nowrap;">struct - localcount *lc</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">localcount_acquire</code>(<var class="Fa" style="white-space: nowrap;">struct - localcount *lc</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">localcount_release</code>(<var class="Fa" style="white-space: nowrap;">struct - localcount *lc</var>, <var class="Fa" style="white-space: nowrap;">struct - kcondvar *cv</var>, <var class="Fa" style="white-space: nowrap;">struct - kmutex *mtx</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">localcount_drain</code>(<var class="Fa" style="white-space: nowrap;">struct - localcount *lc</var>, <var class="Fa" style="white-space: nowrap;">struct - kcondvar *cv</var>, <var class="Fa" style="white-space: nowrap;">struct - kmutex *mtx</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">Localcounts are used in the kernel to implement a medium-weight - reference counting mechanism. During normal operations, localcounts do not - need the interprocessor synchronization associated with - <a class="Xr">atomic_ops(3)</a> atomic memory operations, and (unlike - <a class="Xr">psref(9)</a>) <code class="Nm">localcount</code> references - can be held across sleeps and can migrate between CPUs. Draining a - <code class="Nm">localcount</code> requires more expensive interprocessor - synchronization than <a class="Xr">atomic_ops(3)</a> (similar to - <a class="Xr">psref(9)</a>). And <code class="Nm">localcount</code> - references require eight bytes of memory per object per-CPU, significantly - more than <a class="Xr">atomic_ops(3)</a> and almost always more than - <a class="Xr">psref(9)</a>.</p> -<p class="Pp">As a rough heuristic, <code class="Nm">localcount</code> should be - used for classes of objects of which there are perhaps a few dozen instances - (such as <a class="Xr">autoconf(9)</a> devices) but not thousands of - instances (such as network flows) and on which there may be a mixture of - long-term I/O waits, such as xyzread for a device xyz(4), and short-term - fast operations, such as - <code class="Dv">xyzioctl(IOC_READ_A_CPU_REG)</code>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> -<dl class="Bl-tag"> - <dt id="localcount_init"><a class="permalink" href="#localcount_init"><code class="Fn">localcount_init</code></a>(<var class="Fa">lc</var>)</dt> - <dd>Dynamically initialize localcount <var class="Ar">lc</var> for use. - <p class="Pp">No other operations can be performed on a localcount until it - has been initialized.</p> - </dd> - <dt id="localcount_fini"><a class="permalink" href="#localcount_fini"><code class="Fn">localcount_fini</code></a>(<var class="Fa">lc</var>)</dt> - <dd>Release resources used by localcount <var class="Ar">lc</var>. The caller - must have already called <code class="Fn">localcount_drain</code>(). The - localcount may not be used after <code class="Fn">localcount_fini</code>() - has been called until it has been re-initialized by - <code class="Fn">localcount_init</code>().</dd> - <dt><code class="Fn">localcount_acquire</code>(<var class="Fa">lc</var>)</dt> - <dd>Acquire a reference to the localcount <var class="Ar">lc</var>. - <p class="Pp" id="localcount_acquire">The caller must ensure by some other - mechanism that the localcount will not be destroyed before the call to - <a class="permalink" href="#localcount_acquire"><code class="Fn">localcount_acquire</code></a>(); - typically this will be via a <a class="Xr">pserialize(9)</a> read - section.</p> - </dd> - <dt id="localcount_release"><a class="permalink" href="#localcount_release"><code class="Fn">localcount_release</code></a>(<var class="Fa">lc</var>, - <var class="Fa">cv</var>, <var class="Fa">mtx</var>)</dt> - <dd>Release a reference to the localcount <var class="Ar">lc</var>. If the - localcount is currently being drained, the mutex <var class="Ar">mtx</var> - will be used to synchronize updates to the global reference count (i.e., - the total across all CPUs). If the reference count goes to zero, - <code class="Fn">localcount_release</code>() will broadcast availability - of the condvar <var class="Ar">cv</var>.</dd> - <dt><code class="Fn">localcount_drain</code>(<var class="Fa">lc</var>, - <var class="Fa">cv</var>, <var class="Fa">mtx</var>)</dt> - <dd>Wait for all references to the localcount <var class="Ar">lc</var> to be - released. The caller must hold the mutex <var class="Ar">mtx</var>; the - mutex will be released during inter-CPU cross-calls (see - <a class="Xr">xcall(9)</a>) and while waiting on the condvar - <var class="Ar">cv</var>. The same <var class="Ar">cv</var> and - <var class="Ar">mtx</var> must be used with - <code class="Fn">localcount_release</code>(). - <p class="Pp" id="localcount_acquire~2">The caller must guarantee that no - new references can be acquired with - <a class="permalink" href="#localcount_acquire~2"><code class="Fn">localcount_acquire</code></a>() - before calling <code class="Fn">localcount_drain</code>(). For example, - any object that may be found in a list and acquired must be removed from - the list before calling <code class="Fn">localcount_drain</code>(); - removal from the list would typically be protected by calling - <a class="Xr">pserialize_perform(9)</a> to wait for any - <a class="Xr">pserialize(9)</a> readers to complete.</p> - <p class="Pp" id="localcount_drain">Once the localcount object - <var class="Ar">lc</var> is passed to - <a class="permalink" href="#localcount_drain"><code class="Fn">localcount_drain</code></a>(), - it must be passed to <code class="Fn">localcount_fini</code>() before - any other re-use.</p> - </dd> -</dl> -</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 localcount implementation is located in - <span class="Pa">sys/kern/subr_localcount.c</span>.</p> -<p class="Pp">The header file <span class="Pa">sys/sys/localcount.h</span> - describes the public interface, and interfaces that machine-dependent code - must provide to support localcounts.</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">atomic_ops(3)</a>, <a class="Xr">condvar(9)</a>, - <a class="Xr">mutex(9)</a>, <a class="Xr">psref(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The localcount primitives first appeared in - <span class="Ux">NetBSD 8.0</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp"><code class="Nm">localcount</code> was designed by - <span class="An">Taylor R. Campbell</span>, who also provided a draft - implementation. The implementation was completed, tested, and integrated by - <span class="An">Paul Goyette</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1> -<p class="Pp">The <code class="Nm">localcount</code> facility does not provide - any way to examine the reference count without actually waiting for the - count to reach zero.</p> -<p class="Pp">Waiting for a <code class="Nm">localcount</code> reference count - to drain (reach zero) is a one-shot operation. Once the - <code class="Nm">localcount</code> has been drained, no further operations - are allowed until the <code class="Nm">localcount</code> has been - re-initialized.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">February 25, 2019</td> - <td class="foot-os">NetBSD 10.1</td> - </tr> -</table> |