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 21 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 serialised singly-linked shared reference pointer list operations .Sh SYNOPSIS n sys/srp.h .Ft int .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" .Fo "SRPL_FOREACH_SAFE_LOCKED" .Fa "VARNAME" .Fa "SRPL_HEAD *sl" .Fa "FIELDNAME" .Fa "TEMP_VARNAME" .Fc .Ft void .Fo "SRPL_INSERT_HEAD_LOCKED" .Fa "struct srpl_rc *rc" .Fa "SRPL_HEAD *sl" .Fa "struct TYPE *elm" .Fa "FIELDNAME" .Fc .Ft void .Fo "SRPL_INSERT_AFTER_LOCKED" .Fa "struct srpl_rc *rc" .Fa "struct TYPE *listelm" .Fa "struct TYPE *elm" .Fa "FIELDNAME" .Fc .Ft void .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. These macros allow manipulation and traversal of the linked list while access to the list is serialised by the caller.
p .Fn SRPL_EMPTY_LOCKED tests whether the SRP list .Fa sl is empty.
p .Fn SRPL_FIRST_LOCKED accesses the first element in the SRP list .Fa sl .
p .Fn SRPL_NEXT_LOCKED accesses the next element in the SRP list after .Fa listelm .
p .Fn SRPL_FOREACH_LOCKED creates a loop for traversing the elements in the SRP list .Fa sl .
p .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.
p .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 .
p .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 .
p .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.
p .Fn SRPL_EMPTY_LOCKED returns non-zero when the list is empty, otherwise 0. .Sh SEE ALSO .Xr SRPL_FIRST 9 .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 .