diff options
Diffstat (limited to 'static/freebsd/man9/counter.9 4.html')
| -rw-r--r-- | static/freebsd/man9/counter.9 4.html | 282 |
1 files changed, 0 insertions, 282 deletions
diff --git a/static/freebsd/man9/counter.9 4.html b/static/freebsd/man9/counter.9 4.html deleted file mode 100644 index b9e32121..00000000 --- a/static/freebsd/man9/counter.9 4.html +++ /dev/null @@ -1,282 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">COUNTER(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">COUNTER(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">counter</code> — - <span class="Nd">SMP-friendly kernel counter implementation</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/types.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/systm.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/counter.h</a>></code></p> -<p class="Pp"><var class="Ft">counter_u64_t</var> - <br/> - <code class="Fn">counter_u64_alloc</code>(<var class="Fa" style="white-space: nowrap;">int - wait</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">counter_u64_free</code>(<var class="Fa" style="white-space: nowrap;">counter_u64_t - c</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">counter_u64_add</code>(<var class="Fa" style="white-space: nowrap;">counter_u64_t - c</var>, <var class="Fa" style="white-space: nowrap;">int64_t v</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">counter_enter</code>();</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">counter_exit</code>();</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">counter_u64_add_protected</code>(<var class="Fa" style="white-space: nowrap;">counter_u64_t - c</var>, <var class="Fa" style="white-space: nowrap;">int64_t v</var>);</p> -<p class="Pp"><var class="Ft">uint64_t</var> - <br/> - <code class="Fn">counter_u64_fetch</code>(<var class="Fa" style="white-space: nowrap;">counter_u64_t - c</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">counter_u64_zero</code>(<var class="Fa" style="white-space: nowrap;">counter_u64_t - c</var>);</p> -<p class="Pp"><var class="Ft">struct counter_rate *</var> - <br/> - <code class="Fn">counter_rate_alloc</code>(<var class="Fa" style="white-space: nowrap;">int - flags</var>, <var class="Fa" style="white-space: nowrap;">int - period</var>);</p> -<p class="Pp"><var class="Ft">int64_t</var> - <br/> - <code class="Fn">counter_ratecheck</code>(<var class="Fa" style="white-space: nowrap;">struct - counter_rate *cr</var>, <var class="Fa" style="white-space: nowrap;">int64_t - limit</var>);</p> -<p class="Pp"><var class="Ft">uint64_t</var> - <br/> - <code class="Fn">counter_rate_get</code>(<var class="Fa" style="white-space: nowrap;">struct - counter_rate *cr</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">counter_rate_free</code>(<var class="Fa" style="white-space: nowrap;">struct - counter_rate *cr</var>);</p> -<p class="Pp"><code class="Fn">COUNTER_U64_SYSINIT</code>(<var class="Fa" style="white-space: nowrap;">counter_u64_t - c</var>);</p> -<p class="Pp"><code class="Fn">COUNTER_U64_DEFINE_EARLY</code>(<var class="Fa" style="white-space: nowrap;">counter_u64_t - c</var>);</p> -<p class="Pp"><code class="In">#include - <<a class="In">sys/sysctl.h</a>></code></p> -<p class="Pp"><code class="Fn">SYSCTL_COUNTER_U64</code>(<var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">nbr</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">access</var>, - <var class="Fa" style="white-space: nowrap;">ptr</var>, - <var class="Fa" style="white-space: nowrap;">descr</var>);</p> -<p class="Pp"><code class="Fn">SYSCTL_ADD_COUNTER_U64</code>(<var class="Fa" style="white-space: nowrap;">ctx</var>, - <var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">nbr</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">access</var>, - <var class="Fa" style="white-space: nowrap;">ptr</var>, - <var class="Fa" style="white-space: nowrap;">descr</var>);</p> -<p class="Pp"><code class="Fn">SYSCTL_COUNTER_U64_ARRAY</code>(<var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">nbr</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">access</var>, - <var class="Fa" style="white-space: nowrap;">ptr</var>, - <var class="Fa" style="white-space: nowrap;">len</var>, - <var class="Fa" style="white-space: nowrap;">descr</var>);</p> -<p class="Pp"><code class="Fn">SYSCTL_ADD_COUNTER_U64_ARRAY</code>(<var class="Fa" style="white-space: nowrap;">ctx</var>, - <var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">nbr</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">access</var>, - <var class="Fa" style="white-space: nowrap;">ptr</var>, - <var class="Fa" style="white-space: nowrap;">len</var>, - <var class="Fa" style="white-space: nowrap;">descr</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp"><code class="Nm">counter</code> is a generic facility to create - counters that can be utilized for any purpose (such as collecting - statistical data). A <code class="Nm">counter</code> is guaranteed to be - lossless when several kernel threads do simultaneous updates. However, - <code class="Nm">counter</code> does not block the calling thread, also no - <a class="Xr">atomic(9)</a> operations are used for the update, therefore - the counters can be used in any non-interrupt context. Moreover, - <code class="Nm">counter</code> has special optimisations for SMP - environments, making <code class="Nm">counter</code> update faster than - simple arithmetic on the global variable. Thus - <code class="Nm">counter</code> is considered suitable for accounting in the - performance-critical code paths.</p> -<dl class="Bl-tag"> - <dt id="counter_u64_alloc"><a class="permalink" href="#counter_u64_alloc"><code class="Fn">counter_u64_alloc</code></a>(<var class="Fa">wait</var>)</dt> - <dd>Allocate a new 64-bit unsigned counter. The <var class="Fa">wait</var> - argument is the <a class="Xr">malloc(9)</a> wait flag, should be either - <var class="Va">M_NOWAIT</var> or <var class="Va">M_WAITOK</var>. If - <var class="Va">M_NOWAIT</var> is specified the operation may fail and - return <code class="Dv">NULL</code>.</dd> - <dt id="counter_u64_free"><a class="permalink" href="#counter_u64_free"><code class="Fn">counter_u64_free</code></a>(<var class="Fa">c</var>)</dt> - <dd>Free the previously allocated counter <var class="Fa">c</var>. It is safe - to pass <code class="Dv">NULL</code>.</dd> - <dt id="counter_u64_add"><a class="permalink" href="#counter_u64_add"><code class="Fn">counter_u64_add</code></a>(<var class="Fa">c</var>, - <var class="Fa">v</var>)</dt> - <dd>Add <var class="Fa">v</var> to <var class="Fa">c</var>. The KPI does not - guarantee any protection from wraparound.</dd> - <dt id="counter_enter"><a class="permalink" href="#counter_enter"><code class="Fn">counter_enter</code></a>()</dt> - <dd>Enter mode that would allow the safe update of several counters via - <a class="permalink" href="#counter_u64_add_protected"><code class="Fn" id="counter_u64_add_protected">counter_u64_add_protected</code></a>(). - On some machines this expands to <a class="Xr">critical(9)</a> section, - while on other is a nop. See - <a class="Sx" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION - DETAILS</a>.</dd> - <dt id="counter_exit"><a class="permalink" href="#counter_exit"><code class="Fn">counter_exit</code></a>()</dt> - <dd>Exit mode for updating several counters.</dd> - <dt><code class="Fn">counter_u64_add_protected</code>(<var class="Fa">c</var>, - <var class="Fa">v</var>)</dt> - <dd>Same as <code class="Fn">counter_u64_add</code>(), but should be preceded - by <code class="Fn">counter_enter</code>().</dd> - <dt id="counter_u64_fetch"><a class="permalink" href="#counter_u64_fetch"><code class="Fn">counter_u64_fetch</code></a>(<var class="Fa">c</var>)</dt> - <dd>Take a snapshot of counter <var class="Fa">c</var>. The data obtained is - not guaranteed to reflect the real cumulative value for any moment.</dd> - <dt id="counter_u64_zero"><a class="permalink" href="#counter_u64_zero"><code class="Fn">counter_u64_zero</code></a>(<var class="Fa">c</var>)</dt> - <dd>Clear the counter <var class="Fa">c</var> and set it to zero.</dd> - <dt id="counter_rate_alloc"><a class="permalink" href="#counter_rate_alloc"><code class="Fn">counter_rate_alloc</code></a>(<var class="Fa">flags</var>, - <var class="Fa">period</var>)</dt> - <dd>Allocate a new struct counter_rate. <var class="Fa">flags</var> is passed - to <a class="Xr">malloc(9)</a>. <var class="Fa">period</var> is the time - over which the rate is checked.</dd> - <dt id="counter_ratecheck"><a class="permalink" href="#counter_ratecheck"><code class="Fn">counter_ratecheck</code></a>(<var class="Fa">cr</var>, - <var class="Fa">limit</var>)</dt> - <dd>The function is a multiprocessor-friendly version of - <a class="permalink" href="#ppsratecheck"><code class="Fn" id="ppsratecheck">ppsratecheck</code></a>() - which uses <code class="Nm">counter</code> internally. Returns - non-negative value if the rate is not yet reached during the current - period, and a negative value otherwise. If the limit was reached during - the previous period, but was just reset back to zero, then - <code class="Fn">counter_ratecheck</code>() returns number of events since - previous reset.</dd> - <dt id="counter_rate_get"><a class="permalink" href="#counter_rate_get"><code class="Fn">counter_rate_get</code></a>(<var class="Fa">cr</var>)</dt> - <dd>The number of hits to this check within the current period.</dd> - <dt id="counter_rate_free"><a class="permalink" href="#counter_rate_free"><code class="Fn">counter_rate_free</code></a>(<var class="Fa">cr</var>)</dt> - <dd>Free the <var class="Fa">cr</var> counter.</dd> - <dt id="COUNTER_U64_SYSINIT"><a class="permalink" href="#COUNTER_U64_SYSINIT"><code class="Fn">COUNTER_U64_SYSINIT</code></a>(<var class="Fa">c</var>)</dt> - <dd>Define a <a class="Xr">SYSINIT(9)</a> initializer for the global counter - <var class="Fa">c</var>.</dd> - <dt id="COUNTER_U64_DEFINE_EARLY"><a class="permalink" href="#COUNTER_U64_DEFINE_EARLY"><code class="Fn">COUNTER_U64_DEFINE_EARLY</code></a>(<var class="Fa">c</var>)</dt> - <dd>Define and initialize a global counter <var class="Fa">c</var>. It is - always safe to increment <var class="Fa">c</var>, though updates prior to - the <code class="Dv">SI_SUB_COUNTER</code> <a class="Xr">SYSINIT(9)</a> - event are lost.</dd> - <dt id="SYSCTL_COUNTER_U64"><a class="permalink" href="#SYSCTL_COUNTER_U64"><code class="Fn">SYSCTL_COUNTER_U64</code></a>(<var class="Fa">parent</var>, - <var class="Fa">nbr</var>, <var class="Fa">name</var>, - <var class="Fa">access</var>, <var class="Fa">ptr</var>, - <var class="Fa">descr</var>)</dt> - <dd>Declare a static <a class="Xr">sysctl(9)</a> oid that would represent a - <code class="Nm">counter</code>. The <var class="Fa">ptr</var> argument - should be a pointer to allocated <var class="Vt">counter_u64_t</var>. A - read of the oid returns value obtained through - <code class="Fn">counter_u64_fetch</code>(). Any write to the oid zeroes - it.</dd> - <dt id="SYSCTL_ADD_COUNTER_U64"><a class="permalink" href="#SYSCTL_ADD_COUNTER_U64"><code class="Fn">SYSCTL_ADD_COUNTER_U64</code></a>(<var class="Fa">ctx</var>, - <var class="Fa">parent</var>, <var class="Fa">nbr</var>, - <var class="Fa">name</var>, <var class="Fa">access</var>, - <var class="Fa">ptr</var>, <var class="Fa">descr</var>)</dt> - <dd>Create a <a class="Xr">sysctl(9)</a> oid that would represent a - <code class="Nm">counter</code>. The <var class="Fa">ptr</var> argument - should be a pointer to allocated <var class="Vt">counter_u64_t</var>. A - read of the oid returns value obtained through - <code class="Fn">counter_u64_fetch</code>(). Any write to the oid zeroes - it.</dd> - <dt id="SYSCTL_COUNTER_U64_ARRAY"><a class="permalink" href="#SYSCTL_COUNTER_U64_ARRAY"><code class="Fn">SYSCTL_COUNTER_U64_ARRAY</code></a>(<var class="Fa">parent</var>, - <var class="Fa">nbr</var>, <var class="Fa">name</var>, - <var class="Fa">access</var>, <var class="Fa">ptr</var>, - <var class="Fa">len</var>, <var class="Fa">descr</var>)</dt> - <dd>Declare a static <a class="Xr">sysctl(9)</a> oid that would represent an - array of <code class="Nm">counter</code>. The <var class="Fa">ptr</var> - argument should be a pointer to allocated array of - <var class="Vt">counter_u64_t's</var>. The <var class="Fa">len</var> - argument should specify number of elements in the array. A read of the oid - returns len-sized array of <var class="Vt">uint64_t</var> values obtained - through <code class="Fn">counter_u64_fetch</code>(). Any write to the oid - zeroes all array elements.</dd> - <dt id="SYSCTL_ADD_COUNTER_U64_ARRAY"><a class="permalink" href="#SYSCTL_ADD_COUNTER_U64_ARRAY"><code class="Fn">SYSCTL_ADD_COUNTER_U64_ARRAY</code></a>(<var class="Fa">ctx</var>, - <var class="Fa">parent</var>, <var class="Fa">nbr</var>, - <var class="Fa">name</var>, <var class="Fa">access</var>, - <var class="Fa">ptr</var>, <var class="Fa">len</var>, - <var class="Fa">descr</var>)</dt> - <dd>Create a <a class="Xr">sysctl(9)</a> oid that would represent an array of - <code class="Nm">counter</code>. The <var class="Fa">ptr</var> argument - should be a pointer to allocated array of - <var class="Vt">counter_u64_t's</var>. The <var class="Fa">len</var> - argument should specify number of elements in the array. A read of the oid - returns len-sized array of <var class="Vt">uint64_t</var> values obtained - through <code class="Fn">counter_u64_fetch</code>(). Any write to the oid - zeroes all array elements.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="IMPLEMENTATION_DETAILS"><a class="permalink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION - DETAILS</a></h1> -<p class="Pp">On all architectures <code class="Nm">counter</code> is - implemented using per-CPU data fields that are specially aligned in memory, - to avoid inter-CPU bus traffic due to shared use of the variables between - CPUs. These are allocated using <var class="Va">UMA_ZONE_PCPU</var> - <a class="Xr">uma(9)</a> zone. The update operation only touches the field - that is private to current CPU. Fetch operation loops through all per-CPU - fields and obtains a snapshot sum of all fields.</p> -<p class="Pp">On amd64 a <code class="Nm">counter</code> update is implemented - as a single instruction without lock semantics, operating on the private - data for the current CPU, which is safe against preemption and - interrupts.</p> -<p class="Pp">On i386 architecture, when machine supports the cmpxchg8 - instruction, this instruction is used. The multi-instruction sequence - provides the same guarantees as the amd64 single-instruction - implementation.</p> -<p class="Pp">On some architectures updating a counter require a - <a class="Xr">critical(9)</a> section.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> -<p class="Pp">The following example creates a static counter array exported to - userspace through a sysctl:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>#define MY_SIZE 8 -static counter_u64_t array[MY_SIZE]; -SYSCTL_COUNTER_U64_ARRAY(_debug, OID_AUTO, counter_array, CTLFLAG_RW, - &array[0], MY_SIZE, "Test counter array");</pre> -</div> -</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(9)</a>, <a class="Xr">critical(9)</a>, - <a class="Xr">locking(9)</a>, <a class="Xr">malloc(9)</a>, - <a class="Xr">ratecheck(9)</a>, <a class="Xr">sysctl(9)</a>, - <a class="Xr">SYSINIT(9)</a>, <a class="Xr">uma(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The <code class="Nm">counter</code> facility first appeared in - <span class="Ux">FreeBSD 10.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">counter</code> facility was written by - <span class="An">Gleb Smirnoff</span> and <span class="An">Konstantin - Belousov</span>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">June 19, 2025</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |