Move LOCKED macros to teir own manual.

This will allow us to better document them and add examples.

Disccussed with dlg@

3 files changed, 152 insertions, 112 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 40954168219..03bb5ed57bd 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.283 2016/10/21 10:15:40 dlg Exp $
+#	$OpenBSD: Makefile,v 1.284 2016/11/20 12:05:25 mpi Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -30,7 +30,8 @@ MAN=	aml_evalnode.9 atomic_add_int.9 atomic_cas_uint.9 \
 	RBT_INIT.9 \
 	radio.9 arc4random.9 rasops.9 ratecheck.9 refcnt_init.9 resettodr.9 \
 	rssadapt.9 route.9 rt_ifa_add.9 rt_timer_add.9 rtalloc.9 rtable_add.9 \
-	rtlabel_id2name.9 rtrequest.9 rwlock.9 SipHash24.9 sensor_attach.9 \
+	rtlabel_id2name.9 rtrequest.9 rwlock.9 SRPL_EMPTY_LOCKED.9 SipHash24.9 \
+	sensor_attach.9 \
 	spl.9 srp_enter.9 srpl_rc_init.9 startuphook_establish.9 \
 	socreate.9 sosplice.9 style.9 syscall.9 sysctl_int.9 \
 	task_add.9 tc_init.9 time_second.9 timeout.9 tsleep.9 tvtohz.9 \
diff --git a/share/man/man9/SRPL_EMPTY_LOCKED.9 b/share/man/man9/SRPL_EMPTY_LOCKED.9
new file mode 100644
index 00000000000..5fbb09e5fd5
--- /dev/null
+++ b/share/man/man9/SRPL_EMPTY_LOCKED.9
@@ -0,0 +1,144 @@
+.\"	$OpenBSD: SRPL_EMPTY_LOCKED.9,v 1.1 2016/11/20 12:05:25 mpi Exp $
+.\"
+.\" Copyright (c) 2015 David Gwynne <dlg@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: November 20 2016 $
+.Dt SRPL_EMPTY_LOCKED 9
+.Os
+.Sh NAME
+.Nm SRPL_EMPTY_LOCKED ,
+.Nm SRPL_FIRST_LOCKED ,
+.Nm SRPL_NEXT_LOCKED ,
+.Nm SRPL_FOREACH_LOCKED ,
+.Nm SRPL_FOREACH_SAFE_LOCKED ,
+.Nm SRPL_INSERT_HEAD_LOCKED ,
+.Nm SRPL_INSERT_AFTER_LOCKED ,
+.Nm SRPL_REMOVE_LOCKED ,
+.Nd singly-linked shared reference pointer list
+.Sh SYNOPSIS
+.In sys/srp.h
+.Fn "SRPL_EMPTY_LOCKED" "SRPL_HEAD *sl"
+.Ft void *
+.Fn "SRPL_FIRST_LOCKED" "SRPL_HEAD *sl"
+.Ft void *
+.Fn "SRPL_NEXT_LOCKED" "struct TYPE *listelm" "FIELDNAME"
+.Fn "SRPL_FOREACH_LOCKED" "VARNAME" "SRPL_HEAD *sl" "FIELDNAME"
+.Fn "SRPL_FOREACH_SAFE_LOCKED" "VARNAME" "SRPL_HEAD *sl" "FIELDNAME" "TEMP_VARNAME"
+.Fo "SRPL_INSERT_HEAD_LOCKED"
+.Fa "struct srpl_rc *rc"
+.Fa "SRPL_HEAD *sl"
+.Fa "struct TYPE *elm"
+.Fa "FIELDNAME"
+.Fc
+.Fo "SRPL_INSERT_AFTER_LOCKED"
+.Fa "struct srpl_rc *rc"
+.Fa "struct TYPE *listelm"
+.Fa "struct TYPE *elm"
+.Fa "FIELDNAME"
+.Fc
+.Fo "SRPL_REMOVE_LOCKED"
+.Fa "struct srpl_rc *rc"
+.Fa "SRPL_HEAD *sl"
+.Fa "struct TYPE *listelm"
+.Fa "TYPE"
+.Fa "FIELDNAME"
+.Fc
+.Sh DESCRIPTION
+The SRP list
+macros build a linked list on top of shared reference pointers.
+This allows concurrent traversal of a linked list and access to the
+items on the list.
+.Pp
+.Fn SRPL_EMPTY_LOCKED
+tests whether the SRP list
+.Fa sl
+is empty.
+.Pp
+.Fn SRPL_FIRST_LOCKED
+accesses the first element in the SRP list
+.Fa sl .
+.Pp
+.Fn SRPL_NEXT_LOCKED
+accesses the next element in the SRP list after
+.Fa listelm .
+.Pp
+.Fn SRPL_FOREACH_LOCKED
+creates a loop for traversing the elements in the SRP list
+.Fa sl .
+.Pp
+.Fn SRPL_FOREACH_SAFE_LOCKED
+creates a loop for traversing the elements in the SRP list
+.Fa sl ,
+permitting it to remove
+.Fa VARNAME
+as well as freeing it from within the loop safely without interfering with the
+traversal.
+.Pp
+.Fn SRPL_INSERT_HEAD_LOCKED
+inserts
+.Fa elm
+into the SRP list
+.Fa sl .
+Reference counts are adjusted on the list items using the functions
+specified by
+.Fa rc .
+.Pp
+.Fn SRPL_INSERT_AFTER_LOCKED
+inserts
+.Fa elm
+into an SRP list after the element
+.Fa listelm .
+Reference counts are adjusted on the list items using the functions
+specified by
+.Fa rc .
+.Pp
+.Fn SRPL_REMOVE_LOCKED
+iterates over the SRP list
+.Fa sl
+until it finds
+.Fa listelm
+and then removes it.
+Reference counts are adjusted on the list items using the functions
+specified by
+.Fa rc .
+.Sh CONTEXT
+.Fn SRPL_EMPTY_LOCKED ,
+.Fn SRPL_FIRST_LOCKED ,
+.Fn SRPL_NEXT_LOCKED ,
+.Fn SRPL_FOREACH_LOCKED ,
+.Fn SRPL_INSERT_HEAD_LOCKED ,
+.Fn SRPL_INSERT_AFTER_LOCKED ,
+and
+.Fn SRPL_REMOVE_LOCKED
+may be called during autoconf or from process context.
+An appropriate lock must be held that prevents concurrent modifications
+to the list.
+.Sh RETURN VALUES
+.Fn SRPL_FIRST_LOCKED ,
+and
+.Fn SRPL_NEXT_LOCKED
+return a pointer to elements in the SRP list, or
+.Dv NULL
+if there are no more elements.
+.Pp
+.Fn SRPL_EMPTY_LOCKED
+returns non-zero when the list is empty, otherwise 0.
+.Sh HISTORY
+The srp API was originally written by
+.An Jonathan Matthew Aq Mt jmatthew@openbsd.org
+and
+.An David Gwynne Aq Mt dlg@openbsd.org .
+The SRP list API first appeared in
+.Ox 5.9 .
diff --git a/share/man/man9/srpl_rc_init.9 b/share/man/man9/srpl_rc_init.9
index 87f992aa5c8..33d648c2d80 100644
--- a/share/man/man9/srpl_rc_init.9
+++ b/share/man/man9/srpl_rc_init.9
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: srpl_rc_init.9,v 1.11 2016/11/20 11:40:58 mpi Exp $
+.\"	$OpenBSD: srpl_rc_init.9,v 1.12 2016/11/20 12:05:25 mpi Exp $
 .\"
 .\" Copyright (c) 2015 David Gwynne <dlg@openbsd.org>
 .\"
@@ -27,14 +27,6 @@
 .Nm SRPL_FOLLOW ,
 .Nm SRPL_FOREACH ,
 .Nm SRPL_LEAVE ,
-.Nm SRPL_EMPTY_LOCKED ,
-.Nm SRPL_FIRST_LOCKED ,
-.Nm SRPL_NEXT_LOCKED ,
-.Nm SRPL_FOREACH_LOCKED ,
-.Nm SRPL_FOREACH_SAFE_LOCKED ,
-.Nm SRPL_INSERT_HEAD_LOCKED ,
-.Nm SRPL_INSERT_AFTER_LOCKED ,
-.Nm SRPL_REMOVE_LOCKED ,
 .Nm SRPL_RC_INITIALIZER
 .Nd singly-linked shared reference pointer list
 .Sh SYNOPSIS
@@ -62,41 +54,13 @@
 .Fa "SRPL_HEAD *sl"
 .Fa "FIELDNAME"
 .Fc
-.Fn "SRPL_LEAVE" "struct srp_ref *sr"
-.Fn "SRPL_EMPTY_LOCKED" "SRPL_HEAD *sl"
-.Ft void *
-.Fn "SRPL_FIRST_LOCKED" "SRPL_HEAD *sl"
-.Ft void *
-.Fn "SRPL_NEXT_LOCKED" "struct TYPE *listelm" "FIELDNAME"
-.Fn "SRPL_FOREACH_LOCKED" "VARNAME" "SRPL_HEAD *sl" "FIELDNAME"
-.Fn "SRPL_FOREACH_SAFE_LOCKED" "VARNAME" "SRPL_HEAD *sl" "FIELDNAME" "TEMP_VARNAME"
-.Fo "SRPL_INSERT_HEAD_LOCKED"
-.Fa "struct srpl_rc *rc"
-.Fa "SRPL_HEAD *sl"
-.Fa "struct TYPE *elm"
-.Fa "FIELDNAME"
-.Fc
-.Fo "SRPL_INSERT_AFTER_LOCKED"
-.Fa "struct srpl_rc *rc"
-.Fa "struct TYPE *listelm"
-.Fa "struct TYPE *elm"
-.Fa "FIELDNAME"
-.Fc
-.Fo "SRPL_REMOVE_LOCKED"
-.Fa "struct srpl_rc *rc"
-.Fa "SRPL_HEAD *sl"
-.Fa "struct TYPE *listelm"
-.Fa "TYPE"
-.Fa "FIELDNAME"
-.Fc
 .Fo "SRPL_RC_INITIALIZER"
 .Fa "void (*ref)(void *, void *)"
 .Fa "void (*unref)(void *, void *)"
 .Fa "void *ctx"
 .Fc
 .Sh DESCRIPTION
-The
-srpl
+The SRPL list
 macros build a linked list on top of shared reference pointers.
 This allows concurrent traversal of a linked list and access to the
 items on the list.
@@ -174,71 +138,17 @@ to release references to the list and its elements.
 .Fn SRPL_LEAVE
 releases references to the list and its elements held by previous
 calls to
-.Fn SRPL_FIRST,
+.Fn SRPL_FIRST ,
 .Fn SRPL_NEXT ,
 .Fn SRPL_FOLLOW ,
 or
 .Fn SRPL_FOREACH .
-.Pp
-.Fn SRPL_EMPTY_LOCKED
-tests whether the SRP list
-.Fa sl
-is empty.
-.Pp
-.Fn SRPL_FIRST_LOCKED
-accesses the first element in the SRP list
-.Fa sl .
-.Pp
-.Fn SRPL_NEXT_LOCKED
-accesses the next element in the SRP list after
-.Fa listelm .
-.Pp
-.Fn SRPL_FOREACH_LOCKED
-creates a loop for traversing the elements in the SRP list
-.Fa sl .
-.Pp
-.Fn SRPL_FOREACH_SAFE_LOCKED
-creates a loop for traversing the elements in the SRP list
-.Fa sl ,
-permitting it to remove
-.Fa VARNAME
-as well as freeing it from within the loop safely without interfering with the
-traversal.
-.Pp
-.Fn SRPL_INSERT_HEAD_LOCKED
-inserts
-.Fa elm
-into the SRP list
-.Fa sl .
-Reference counts are adjusted on the list items using the functions
-specified by
-.Fa rc .
-.Pp
-.Fn SRPL_INSERT_AFTER_LOCKED
-inserts
-.Fa elm
-into an SRP list after the element
-.Fa listelm .
-Reference counts are adjusted on the list items using the functions
-specified by
-.Fa rc .
-.Pp
-.Fn SRPL_REMOVE_LOCKED
-iterates over the SRP list
-.Fa sl
-until it finds
-.Fa listelm
-and then removes it.
-Reference counts are adjusted on the list items using the functions
-specified by
-.Fa rc .
-.Pp
 An srpl_rc declaration can be initialised with the
 .Fn SRPL_RC_INITIALIZER
 macro.
 .Sh CONTEXT
 .Fn SRPL_INIT ,
-.Fn SRPL_FIRST,
+.Fn SRPL_FIRST ,
 .Fn SRPL_NEXT ,
 .Fn SRPL_FOLLOW ,
 .Fn SRPL_FOREACH ,
@@ -248,30 +158,15 @@ may be called during autoconf, from process context, or from interrupt
 context.
 .Pp
 .Fn srpl_rc_init ,
-.Fn SRPL_EMPTY_LOCKED ,
-.Fn SRPL_FIRST_LOCKED ,
-.Fn SRPL_NEXT_LOCKED ,
-.Fn SRPL_FOREACH_LOCKED ,
-.Fn SRPL_INSERT_HEAD_LOCKED ,
-.Fn SRPL_INSERT_AFTER_LOCKED ,
-and
-.Fn SRPL_REMOVE_LOCKED
 may be called during autoconf or from process context.
-An appropriate lock must be held that prevents concurrent modifications
-to the list.
 .Sh RETURN VALUES
 .Fn SRPL_FIRST ,
 .Fn SRPL_NEXT ,
-.Fn SRPL_FOLLOW ,
-.Fn SRPL_FIRST_LOCKED ,
 and
-.Fn SRPL_NEXT_LOCKED
+.Fn SRPL_FOLLOW
 return a pointer to elements in the SRP list, or
 .Dv NULL
 if there are no more elements.
-.Pp
-.Fn SRPL_EMPTY_LOCKED
-returns non-zero when the list is empty, otherwise 0.
 .Sh HISTORY
 The srp API was originally written by
 .An Jonathan Matthew Aq Mt jmatthew@openbsd.org