git: ea95173dbb3b - main - unr(9): document iterators

The branch main has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=ea95173dbb3b67019a83155e55f798d4618f18c7

commit ea95173dbb3b67019a83155e55f798d4618f18c7
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2023-05-14 01:40:08 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2023-05-29 22:10:36 +0000

    unr(9): document iterators
    
    Reviewed by:    markj
    Sponsored by:   The FreeBSD Foundation
    MFC after:      1 week
    Differential revision:  https://reviews.freebsd.org/D40089
---
 share/man/man9/unr.9 | 46 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 45 insertions(+), 1 deletion(-)

diff --git a/share/man/man9/unr.9 b/share/man/man9/unr.9
index c0cf44b9033e..201717ccdfd2 100644
--- a/share/man/man9/unr.9
+++ b/share/man/man9/unr.9
@@ -34,7 +34,10 @@
 .Nm delete_unrhdr ,
 .Nm alloc_unr ,
 .Nm alloc_unr_specific ,
-.Nm free_unr
+.Nm free_unr ,
+.Nm create_iter_unr ,
+.Nm next_iter_unr ,
+.Nm free_iter_unr
 .Nd "kernel unit number allocator"
 .Sh SYNOPSIS
 .In sys/systm.h
@@ -56,6 +59,12 @@
 .Fn alloc_unr_specific "struct unrhdr *uh" "u_int item"
 .Ft void
 .Fn free_unr "struct unrhdr *uh" "u_int item"
+.Ft void *
+.Fn create_iter_unr "struct unrhdr *uh"
+.Ft int
+.Fn next_iter_unr "void *handle"
+.Ft void
+.Fn free_iter_unr "void *handle"
 .Sh DESCRIPTION
 The kernel unit number allocator is a generic facility, which allows to allocate
 unit numbers within a specified range.
@@ -135,6 +144,41 @@ Free a previously allocated unit number.
 This function may require allocating memory, and thus it can sleep.
 There is no pre-locked variant.
 .El
+.Sh ITERATOR INTERFACE
+The
+.Nm unr
+facility provides an interface to iterate over all allocated units
+for the given
+.Dv unrhdr .
+Iterators are identified by an opaque handle.
+More than one iterators can operate simultaneously; the iterator position
+data is recorded only in the iterator handle.
+.Pp
+Consumers must ensure that the unit allocator is not modified between
+calls to the iterator functions.
+In particular, the internal allocator mutex cannot provide consistency,
+because it is acquired and dropped inside the
+.Fn next_iter_unr
+function.
+If the allocator was modified, it is safe to free the iterator with
+.Fn free_iter_unr
+method nevertheless.
+.Bl -tag -width indent
+.It Fn create_iter_unr uh
+Create an iterator.
+Return the handle that should be passed to other iterator functions.
+.It Fn next_iter_unr handle
+Return the value of the next unit.
+Units are returned in ascending order.
+A return value of
+.Li \-1
+indicates the end of iteration, in which
+case
+.Li \-1
+is returned for all future calls.
+.It Fn free_iter_unr handle
+Free the iterator, handle is no longer valid.
+.El
 .Sh CODE REFERENCES
 The above functions are implemented in
 .Pa sys/kern/subr_unit.c .