diff options
Diffstat (limited to 'static/freebsd/man9/hashalloc.9 3.html')
| -rw-r--r-- | static/freebsd/man9/hashalloc.9 3.html | 253 |
1 files changed, 0 insertions, 253 deletions
diff --git a/static/freebsd/man9/hashalloc.9 3.html b/static/freebsd/man9/hashalloc.9 3.html deleted file mode 100644 index c53cd5aa..00000000 --- a/static/freebsd/man9/hashalloc.9 3.html +++ /dev/null @@ -1,253 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">HASHALLOC(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">HASHALLOC(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">hashalloc</code>, - <code class="Nm">hashfree</code> — <span class="Nd">allocate and free - kernel hash tables</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/malloc.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/hash.h</a>></code></p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">hashalloc</code>(<var class="Fa" style="white-space: nowrap;">struct - hashalloc_args *args</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">hashfree</code>(<var class="Fa" style="white-space: nowrap;">void - *table</var>, <var class="Fa" style="white-space: nowrap;">struct - hashalloc_args *args</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The - <a class="permalink" href="#hashalloc"><code class="Fn" id="hashalloc">hashalloc</code></a>() - and <code class="Fn">hashfree</code>() functions provide a flexible kernel - programming interface (KPI) for allocating and freeing hash tables with - configurable bucket headers.</p> -<p class="Pp" id="hashalloc~2"><a class="permalink" href="#hashalloc~2"><code class="Fn">hashalloc</code></a>() - allocates memory for a hash table according to the parameters specified in - the <var class="Fa">args</var> structure. It computes an appropriate number - of buckets (adjusting <var class="Fa">args->size</var> as needed based on - the requested <var class="Fa">type</var>), allocates memory using - <a class="Xr">malloc(9)</a>, initializes each bucket's queue header (e.g., - <var class="Vt">LIST_HEAD</var>, <var class="Vt">TAILQ_HEAD</var>, etc.), - and, if requested, initializes per-bucket locks. The returned memory - allocation can be used as an array of header structures that start with - initialized list header of the requested type followed by initialized lock - of requested type.</p> -<p class="Pp" id="hashfree"><a class="permalink" href="#hashfree"><code class="Fn">hashfree</code></a>() - frees a hash table previously allocated by - <code class="Fn">hashalloc</code>().</p> -<p class="Pp">Both functions require the caller to pass the same (or equivalent) - <var class="Fa">struct hashalloc_args</var> that specifies the desired - configuration of the hash table and has the following members:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>struct hashalloc_args { - /* Required arguments */ - size_t size; /* in: desired buckets, out: allocated */ - int mflags; /* malloc(9) flags */ - struct malloc_type *mtype; /* malloc(9) type */ - /* Optional arguments */ - size_t hdrsize; /* bucket header size; 0 = auto */ - enum { - HASH_TYPE_POWER2, - HASH_TYPE_PRIME, - } type; /* default HASH_TYPE_POWER2 */ - enum { - HASH_HEAD_LIST, - HASH_HEAD_CK_LIST, - HASH_HEAD_SLIST, - HASH_HEAD_CK_SLIST, - HASH_HEAD_STAILQ, - HASH_HEAD_CK_STAILQ, - HASH_HEAD_TAILQ, - } head; /* default HASH_HEAD_LIST */ - enum { - HASH_LOCK_NONE, - HASH_LOCK_MTX, - HASH_LOCK_RWLOCK, - HASH_LOCK_SX, - HASH_LOCK_RMLOCK, - HASH_LOCK_RMSLOCK, - } lock; /* default HASH_LOCK_NONE */ - int lopts; /* lock init options */ - const char *lname; /* lock name */ - int (*ctor)(void *); /* bucket constructor */ - void (*dtor)(void *); /* bucket destructor */ - /* Returned arguments */ - int error; /* error code in case of failure */ -};</pre> -</div> -<p class="Pp" id="hashalloc~3">Argument members <var class="Fa">size</var>, - <var class="Fa">mflags</var> and <var class="Fa">mtype</var> are required - for the - <a class="permalink" href="#hashalloc~3"><code class="Fn">hashalloc</code></a>(). - The argument <var class="Fa">size</var>, as filled by earlier call to - <code class="Fn">hashalloc</code>(), and <var class="Fa">mtype</var> are - required for the <code class="Fn">hashfree</code>(). The rest of arguments - are optional and have reasonable defaults. A hash table that was allocated - with a non-default allocation arguments shall pass the same arguments to - <code class="Fn">hashfree</code>(). The structure shall be initialized with - sparse C99 initializer as it may contain opaque extension members. The - structure may be allocated on the stack of a caller.</p> -<dl class="Bl-tag"> - <dt><var class="Fa">size</var></dt> - <dd>Desired number of buckets for <code class="Fn">hashalloc</code>(). Upon a - successful return <code class="Fn">hashalloc</code>() sets this member to - the actual number allocated (may be rounded up to power-of-2 or nearest - prime). The value returned by <code class="Fn">hashalloc</code>() shall be - later supplied to the <code class="Fn">hashfree</code>().</dd> - <dt><var class="Fa">mflags</var>, <var class="Fa">mtype</var></dt> - <dd>Passed directly to <a class="Xr">malloc(9)</a>.</dd> - <dt><var class="Fa">hdrsize</var></dt> - <dd>Optional member that allows the caller to set a different (increased) size - of a bucket header.</dd> - <dt><var class="Fa">type</var></dt> - <dd>Bucket count policy: - <dl class="Bl-tag"> - <dt id="HASH_TYPE_POWER2"><a class="permalink" href="#HASH_TYPE_POWER2"><code class="Dv">HASH_TYPE_POWER2</code></a></dt> - <dd>Rounded up to largest power of two less than or equal to argument - <var class="Fa">size</var>.</dd> - <dt id="HASH_TYPE_PRIME"><a class="permalink" href="#HASH_TYPE_PRIME"><code class="Dv">HASH_TYPE_PRIME</code></a></dt> - <dd>Sized to the largest prime number less than or equal to argument - <var class="Fa">size</var>.</dd> - </dl> - <p class="Pp">Default is <code class="Dv">HASH_TYPE_POWER2</code>.</p> - </dd> - <dt><var class="Fa">head</var></dt> - <dd>Queue header type for each bucket, a <a class="Xr">queue(3)</a> or - Concurrency-kit (CK) type. - <dl class="Bl-tag"> - <dt id="HASH_HEAD_LIST"><a class="permalink" href="#HASH_HEAD_LIST"><code class="Dv">HASH_HEAD_LIST</code></a></dt> - <dd><a class="Xr">queue(3)</a> <code class="Fd">LIST_HEAD</code></dd> - <dt id="HASH_HEAD_CK_LIST"><a class="permalink" href="#HASH_HEAD_CK_LIST"><code class="Dv">HASH_HEAD_CK_LIST</code></a></dt> - <dd>Concurrency-kit <code class="Fd">CK_LIST_HEAD</code></dd> - <dt id="HASH_HEAD_SLIST"><a class="permalink" href="#HASH_HEAD_SLIST"><code class="Dv">HASH_HEAD_SLIST</code></a></dt> - <dd><a class="Xr">queue(3)</a> <code class="Fd">SLIST_HEAD</code></dd> - <dt id="HASH_HEAD_CK_SLIST"><a class="permalink" href="#HASH_HEAD_CK_SLIST"><code class="Dv">HASH_HEAD_CK_SLIST</code></a></dt> - <dd>Concurrency-kit <code class="Fd">CK_SLIST_HEAD</code></dd> - <dt id="HASH_HEAD_STAILQ"><a class="permalink" href="#HASH_HEAD_STAILQ"><code class="Dv">HASH_HEAD_STAILQ</code></a></dt> - <dd><a class="Xr">queue(3)</a> <code class="Fd">STAILQ_HEAD</code></dd> - <dt id="HASH_HEAD_CK_STAILQ"><a class="permalink" href="#HASH_HEAD_CK_STAILQ"><code class="Dv">HASH_HEAD_CK_STAILQ</code></a></dt> - <dd>Concurrency-kit <code class="Fd">CK_STAILQ_HEAD</code></dd> - <dt id="HASH_HEAD_TAILQ"><a class="permalink" href="#HASH_HEAD_TAILQ"><code class="Dv">HASH_HEAD_TAILQ</code></a></dt> - <dd><a class="Xr">queue(3)</a> <code class="Fd">TAILQ_HEAD</code></dd> - </dl> - <p class="Pp">Default is <code class="Dv">HASH_HEAD_LIST</code>.</p> - </dd> - <dt><var class="Fa">lock</var></dt> - <dd>Synchronization: - <dl class="Bl-tag"> - <dt id="HASH_LOCK_NONE"><a class="permalink" href="#HASH_LOCK_NONE"><code class="Dv">HASH_LOCK_NONE</code></a></dt> - <dd>No per-bucket lock.</dd> - <dt id="HASH_LOCK_MTX"><a class="permalink" href="#HASH_LOCK_MTX"><code class="Dv">HASH_LOCK_MTX</code></a></dt> - <dd>Per-bucket <a class="Xr">mutex(9)</a>.</dd> - <dt id="HASH_LOCK_RWLOCK"><a class="permalink" href="#HASH_LOCK_RWLOCK"><code class="Dv">HASH_LOCK_RWLOCK</code></a></dt> - <dd>Per-bucket <a class="Xr">rwlock(9)</a>.</dd> - <dt id="HASH_LOCK_SX"><a class="permalink" href="#HASH_LOCK_SX"><code class="Dv">HASH_LOCK_SX</code></a></dt> - <dd>Per-bucket <a class="Xr">sx(9)</a>.</dd> - <dt id="HASH_LOCK_RMLOCK"><a class="permalink" href="#HASH_LOCK_RMLOCK"><code class="Dv">HASH_LOCK_RMLOCK</code></a></dt> - <dd>Per-bucket <a class="Xr">rmlock(9)</a>.</dd> - <dt id="HASH_LOCK_RMSLOCK"><a class="permalink" href="#HASH_LOCK_RMSLOCK"><code class="Dv">HASH_LOCK_RMSLOCK</code></a></dt> - <dd>Per-bucket sleepable (rms) <a class="Xr">rmlock(9)</a>.</dd> - </dl> - <p class="Pp">Default is <code class="Dv">HASH_LOCK_NONE</code>.</p> - </dd> - <dt><var class="Fa">lopts</var></dt> - <dd>Options passed to <a class="Xr">mtx_init(9)</a>, - <a class="Xr">rw_init(9)</a>, <a class="Xr">sx_init(9)</a>, - <a class="Xr">rm_init(9)</a> or <a class="Xr">rms_init(9)</a> (if locking - is enabled).</dd> - <dt><var class="Fa">lname</var></dt> - <dd>Lock name. This member is required unless <var class="Fa">lock</var> is - <code class="Dv">HASH_LOCK_NONE</code>.</dd> - <dt id="hashalloc~4"><var class="Fa">ctor</var></dt> - <dd>Optional constructor to be called by - <a class="permalink" href="#hashalloc~4"><code class="Fn">hashalloc</code></a>() - for each bucket after list header and lock initialization. May fail with - error code, yielding in a failure of - <code class="Fn">hashalloc</code>().</dd> - <dt><var class="Fa">dtor</var></dt> - <dd>Optional destructor to be called by <code class="Fn">hashfree</code>() for - each bucket before lock destructors and list emptyness checks.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN - VALUES</a></h1> -<p class="Pp"><code class="Fn">hashalloc</code>() returns a pointer to the - allocated and initialized hash table on success, or - <code class="Dv">NULL</code> on memory allocation failure or constructor - failure. The <var class="Fa">error</var> member of - <var class="Fa">args</var> is set to appropriate error code. When - <var class="Fa">mflags</var> in <var class="Fa">args</var> contain the - <var class="Va">M_WAITOK</var> flag and the <var class="Fa">ctor</var> is - either NULL or never fails, then <code class="Fn">hashalloc</code>() never - fails.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> -<p class="Pp">A simple mutex-protected hash table using TAILQ buckets:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>struct bucket { - TAILQ_HEAD(, foo) head; - struct mtx lock; -} *table; - -struct hashalloc_args args = { - .size = 9000, - .mflags = M_WAITOK, - .mtype = M_FOO, - .head = HASH_HEAD_TAILQ, - .lock = HASH_LOCK_MTX, - .lopts = MTX_DEF, - .lname = "bucket of foo", -}; - -table = hashalloc(&args); -/* Use table as array of struct bucket ... */ -mtx_lock(&table[hash].lock); -TAILQ_INSERT_HEAD(&table[hash].head, foo, next); - -/* Later */ -hashfree(table, &args);</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">malloc(9)</a>, <a class="Xr">mutex(9)</a>, - <a class="Xr">rmlock(9)</a>, <a class="Xr">rwlock(9)</a>, - <a class="Xr">sx(9)</a>, <a class="Xr">queue(3)</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">hashalloc</code> KPI first appeared in - <span class="Ux">FreeBSD 16.0</span>. It supersedes older interface - <code class="Fn">hashinit</code>(), that was available since - <span class="Ux">4.4BSD</span>, by offering greater control over the hash - table structure and locking strategy.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp"><span class="An">Gleb Smirnoff</span> - <<a class="Mt" href="mailto:glebius@FreeBSD.org">glebius@FreeBSD.org</a>></p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">April 12, 2026</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |