From nobody Mon Jun 05 08:36:10 2023 X-Original-To: dev-commits-src-branches@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 4QZRlb1MCmz4bLsl; Mon, 5 Jun 2023 08:36:11 +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 4QZRlb0xC8z3xFG; Mon, 5 Jun 2023 08:36:11 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1685954171; 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=9iscgdeh92DYY0oav6JxWF5q2JnJ9BpKGtUuwBASOT4=; b=NvWIj3d/a3TERE7eu/1Nv+xFILOSYRsC1k1cv8oZDy7SDuc+rE9Y14xaoiLzDWGVhHSBOP U8DBmJlNdUV81GKKMXEajqPNFhGzr1BABD/Fcbkq3m0CqqoNmBTVptfOKKKOgO6bC7Gvuv 33h1LgTSVGPWZaT5TlvuA786wYR0ilitLDe1bdcaraAuD9PhunVbqPZASIDewS3U0rUoke 6ci+9/EWoykAKJ2rKa8q3QbYnfnnPCkFiqratJQriyjzPxMJCfk/yZRfb7HwPf4MGD0pWN b3yy2/3EaIrk8YlTBVFdt+F75NPwxGxTz4AQn9TLXECKCQooD7DfQ8aBkwpocw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1685954171; 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=9iscgdeh92DYY0oav6JxWF5q2JnJ9BpKGtUuwBASOT4=; b=ozcctHn1a3Tgz4lk9TBF4I2yiPMZzh83jOI7P5RHYzVjZEiL30j1koHaHH2yOWsmNob2dx UtyPqQL2M/zMRMLJASYMveBnWesHGv0usiHeXBN6ijfmH8lPIC/DOCvqEU9SkDsGTPQzu+ 5Y8BM5unS+3830oC7FgRaAcRq3ZTDXwN/tfFe75e1GMZMFUHFxUffRiT9qEFJid+GiVcN3 kl02btG1AGuMst9IB94MmB+ClwIWOrK6yTDPthRAtiw/nuussp8kPPeuolCqF9z/DAtzA2 JpSV8HOiV2q9//5aQrLEX2nLbXmJ5s4U0SPVb7msjTCCjKBf0iCTRJQ8dUlWLQ== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1685954171; a=rsa-sha256; cv=none; b=i3IXxps3N6hvVOr3s6zk5i+IDHyCv6rNqPg0hhp4MuDTD9gjTA8igfYjGDGR1rEZd8oSdr 7Gki3FVVEyNajKO1RkFPw+rdV3Qt/JNqaaFA0bmqYM26hgVzmxR7Ni7Y+2Oa/PjjgkeVf+ vFzOpVAtdwNaEWHQkaLdT1dP3T7ZCljAIyiFLzptiuxcjlbCPXEh2Hi0y55WOOavtoIYyh clPCU3HPP1XXNBT3wqZgnl7bJXgieLswsjFPlhb67k0uknF/2BECqxKqrU8mFeCB2g3wuM sc4LpGVMFbIZ2QaadhX2NyAD9ssGHBfmZEjoxm/CFJQ7vrCGTv/J0AJ1FVi4lg== 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 4QZRlZ75m0zgMP; Mon, 5 Jun 2023 08:36:10 +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 3558aAbi024520; Mon, 5 Jun 2023 08:36:10 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 3558aAW5024519; Mon, 5 Jun 2023 08:36:10 GMT (envelope-from git) Date: Mon, 5 Jun 2023 08:36:10 GMT Message-Id: <202306050836.3558aAW5024519@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Konstantin Belousov Subject: git: 135bc1d49de5 - stable/13 - unr(9): document iterators List-Id: Commits to the stable branches of the FreeBSD src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-branches List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-branches@freebsd.org X-BeenThere: dev-commits-src-branches@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/stable/13 X-Git-Reftype: branch X-Git-Commit: 135bc1d49de598a8c1c0b679e70265e01d08beea Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch stable/13 has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=135bc1d49de598a8c1c0b679e70265e01d08beea commit 135bc1d49de598a8c1c0b679e70265e01d08beea Author: Konstantin Belousov AuthorDate: 2023-05-14 01:40:08 +0000 Commit: Konstantin Belousov CommitDate: 2023-06-05 08:35:01 +0000 unr(9): document iterators (cherry picked from commit ea95173dbb3b67019a83155e55f798d4618f18c7) --- 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 .