git: 4ae4e074ebe8 - stable/13 - unr(9): document clean_unrhdr()

The branch stable/13 has been updated by kib:

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

commit 4ae4e074ebe8d1ffa749ae7444b1704acc2b25d2
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2023-05-14 00:43:54 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2023-06-05 08:35:01 +0000

    unr(9): document clean_unrhdr()
    
    (cherry picked from commit f8c37080853c13ada935e7fe3d53286c1d9220f1)
---
 share/man/man9/unr.9 | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/share/man/man9/unr.9 b/share/man/man9/unr.9
index c2e9b3943829..c0cf44b9033e 100644
--- a/share/man/man9/unr.9
+++ b/share/man/man9/unr.9
@@ -29,6 +29,7 @@
 .Os
 .Sh NAME
 .Nm new_unrhdr ,
+.Nm clean_unrhdr ,
 .Nm clear_unrhdr ,
 .Nm delete_unrhdr ,
 .Nm alloc_unr ,
@@ -40,6 +41,10 @@
 .Ft "struct unrhdr *"
 .Fn new_unrhdr "int low" "int high" "struct mtx *mutex"
 .Ft void
+.Fn clean_unrhdr "struct unrhdr *uh"
+.Ft void
+.Fn clean_unrhdrl "struct unrhdr *uh"
+.Ft void
 .Fn clear_unrhdr "struct unrhdr *uh"
 .Ft void
 .Fn delete_unrhdr "struct unrhdr *uh"
@@ -86,6 +91,26 @@ This function frees the memory associated with the entity, it does not free
 any units.
 To free all units use
 .Fn clear_unrhdr .
+.It Fn clean_unrhdr uh
+Freeing unit numbers might result in some internal memory becoming unused.
+There are
+.Nm unit
+allocator consumers that cannot tolerate taking
+.Xr malloc 9
+locks to free the memory, while having their unit mutex locked.
+For this reason, free of the unused memory after delete is postponed
+until the consumer can afford calling into the
+.Xr malloc 9
+subsystem.
+Call
+.Fn clean_unrhdr uh
+to do the cleanup.
+In particular, this needs to be done before freeing a unr, if
+a deletion of units could have been performed.
+.It Fn clean_unrhdrl
+Same as
+.Fn clean_unrhdr ,
+but assumes that the unr mutex is already owned, if any.
 .It Fn alloc_unr uh
 Return a new unit number.
 The lowest free number is always allocated.