From nobody Mon May 29 22:11:27 2023 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4QVV9W44Qzz4XFqh; Mon, 29 May 2023 22:11:27 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4QVV9W3Hxgz3Kcf; Mon, 29 May 2023 22:11:27 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1685398287; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=2a5uV5iXGoK3CielgAZaPOc2dP2/Pw8L9AU2jKs6kNw=; b=XYKsDMvf5QvLc21v0HRsfpiZe37rYZ/MFlbkO+XsKS0GL9c9a71xnyU/I8Ve8mSZLkWpad 2AridSEyKhbT7nIIgAxWrksEFx/+SqgyTh6YJVuqJveIYUa7BWEgfBMwvAMe1YwUatfVpd CXseY7rd8aDhZNUjzoTdivAqW507pfz1QL5Njyu5QRw5IXuzRRMMEzmDJDI1Yn8RCCWMAI litxfQ56RFEd+dYcXLIok+DVXke/oCmsOYeNpRktU/q7OFSG5eqQlnndhZvIjm0iQ8v2rp lkksrITR+n8uJdC4asXjdRtwQXv8UO4Svxq2yX/0oRkwydWm9skS0xwQzXUZaw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1685398287; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=2a5uV5iXGoK3CielgAZaPOc2dP2/Pw8L9AU2jKs6kNw=; b=ga/F1ZvOd7xS0xzKDhD9IPhnDLrU8tlYzixCcZPF8W1lJhW1o1qDu/7uPtmGdwY0JzjIcH buK8OMDqxZcYEcw2UnI/Ny0Q+bIRM/fKR0d4snupS3dv92FU2L7yRVZaKprJmKh5QTjqNZ dIGCXBPytU4YNm7l9T+9E8Gi6aOyJK5gcNtTxNfzfFL92BcJXX1SrlrFusI/SGVcohxeQb Dg8CTNtv3jXYhjPArADfRBcyvHA7nPeqHpk6j7lMNVCPnnVUOYLP1FWyyeVhSemvFwV7t3 GmrYnMTcdRa2PpHbqDoV+POGqkGq4RLY6KqS//riWDCqV8nNXlvOHXwJ4Xz9pw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1685398287; a=rsa-sha256; cv=none; b=aB4Ntz39RqXcO1QCMZUUeas+6+iTM6JpE1WDW8/tBMAQvmodNCe2UWMKsG9LVwvX/i38Lk QdaKqdytE2CBshyTjr/UaqmAshd3+4fIX/QOkAfhI7CS9zJAr8I3ANRnj2qMPXkw7wxv5N 2vDwMirg9KMlzNJTa7Mra51symclshR/7P42NN1UoE8yyERniMNTQI0dwvXGFgeTf8hbAC SL1mvUn9Vhmx9o6U5MGjwSICid0N9Hr66vtqWcOd8Pnt+KUjyV5vIO8qc5ijnP/fDn/uvP yfayRKPHlA+feFnAxR66S3B0lXjFq02+2Fy7viyv9ZQ3KYPvU42kbKbdB3Bhrw== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4QVV9W2MNXzT89; Mon, 29 May 2023 22:11:27 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 34TMBRTf044838; Mon, 29 May 2023 22:11:27 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 34TMBRn0044837; Mon, 29 May 2023 22:11:27 GMT (envelope-from git) Date: Mon, 29 May 2023 22:11:27 GMT Message-Id: <202305292211.34TMBRn0044837@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Konstantin Belousov Subject: git: ea95173dbb3b - main - unr(9): document iterators List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-main@freebsd.org X-BeenThere: dev-commits-src-main@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: kib X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: ea95173dbb3b67019a83155e55f798d4618f18c7 Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=ea95173dbb3b67019a83155e55f798d4618f18c7 commit ea95173dbb3b67019a83155e55f798d4618f18c7 Author: Konstantin Belousov AuthorDate: 2023-05-14 01:40:08 +0000 Commit: Konstantin Belousov 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 .