1.\" $OpenBSD: SRPL_EMPTY_LOCKED.9,v 1.3 2016/11/21 07:11:13 dlg Exp $ 2.\" 3.\" Copyright (c) 2015 David Gwynne <dlg@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: November 21 2016 $ 18.Dt SRPL_EMPTY_LOCKED 9 19.Os 20.Sh NAME 21.Nm SRPL_EMPTY_LOCKED , 22.Nm SRPL_FIRST_LOCKED , 23.Nm SRPL_NEXT_LOCKED , 24.Nm SRPL_FOREACH_LOCKED , 25.Nm SRPL_FOREACH_SAFE_LOCKED , 26.Nm SRPL_INSERT_HEAD_LOCKED , 27.Nm SRPL_INSERT_AFTER_LOCKED , 28.Nm SRPL_REMOVE_LOCKED 29.Nd serialised singly-linked shared reference pointer list operations 30.Sh SYNOPSIS 31.In sys/srp.h 32.Ft int 33.Fn "SRPL_EMPTY_LOCKED" "SRPL_HEAD *sl" 34.Ft void * 35.Fn "SRPL_FIRST_LOCKED" "SRPL_HEAD *sl" 36.Ft void * 37.Fn "SRPL_NEXT_LOCKED" "struct TYPE *listelm" "FIELDNAME" 38.Fn "SRPL_FOREACH_LOCKED" "VARNAME" "SRPL_HEAD *sl" "FIELDNAME" 39.Fo "SRPL_FOREACH_SAFE_LOCKED" 40.Fa "VARNAME" 41.Fa "SRPL_HEAD *sl" 42.Fa "FIELDNAME" 43.Fa "TEMP_VARNAME" 44.Fc 45.Ft void 46.Fo "SRPL_INSERT_HEAD_LOCKED" 47.Fa "struct srpl_rc *rc" 48.Fa "SRPL_HEAD *sl" 49.Fa "struct TYPE *elm" 50.Fa "FIELDNAME" 51.Fc 52.Ft void 53.Fo "SRPL_INSERT_AFTER_LOCKED" 54.Fa "struct srpl_rc *rc" 55.Fa "struct TYPE *listelm" 56.Fa "struct TYPE *elm" 57.Fa "FIELDNAME" 58.Fc 59.Ft void 60.Fo "SRPL_REMOVE_LOCKED" 61.Fa "struct srpl_rc *rc" 62.Fa "SRPL_HEAD *sl" 63.Fa "struct TYPE *listelm" 64.Fa "TYPE" 65.Fa "FIELDNAME" 66.Fc 67.Sh DESCRIPTION 68The SRP list 69macros build a linked list on top of shared reference pointers. 70These macros allow manipulation and traversal of the linked list while 71access to the list is serialised by the caller. 72.Pp 73.Fn SRPL_EMPTY_LOCKED 74tests whether the SRP list 75.Fa sl 76is empty. 77.Pp 78.Fn SRPL_FIRST_LOCKED 79accesses the first element in the SRP list 80.Fa sl . 81.Pp 82.Fn SRPL_NEXT_LOCKED 83accesses the next element in the SRP list after 84.Fa listelm . 85.Pp 86.Fn SRPL_FOREACH_LOCKED 87creates a loop for traversing the elements in the SRP list 88.Fa sl . 89.Pp 90.Fn SRPL_FOREACH_SAFE_LOCKED 91creates a loop for traversing the elements in the SRP list 92.Fa sl , 93permitting it to remove 94.Fa VARNAME 95as well as freeing it from within the loop safely without interfering with the 96traversal. 97.Pp 98.Fn SRPL_INSERT_HEAD_LOCKED 99inserts 100.Fa elm 101into the SRP list 102.Fa sl . 103Reference counts are adjusted on the list items using the functions 104specified by 105.Fa rc . 106.Pp 107.Fn SRPL_INSERT_AFTER_LOCKED 108inserts 109.Fa elm 110into an SRP list after the element 111.Fa listelm . 112Reference counts are adjusted on the list items using the functions 113specified by 114.Fa rc . 115.Pp 116.Fn SRPL_REMOVE_LOCKED 117iterates over the SRP list 118.Fa sl 119until it finds 120.Fa listelm 121and then removes it. 122Reference counts are adjusted on the list items using the functions 123specified by 124.Fa rc . 125.Sh CONTEXT 126.Fn SRPL_EMPTY_LOCKED , 127.Fn SRPL_FIRST_LOCKED , 128.Fn SRPL_NEXT_LOCKED , 129.Fn SRPL_FOREACH_LOCKED , 130.Fn SRPL_INSERT_HEAD_LOCKED , 131.Fn SRPL_INSERT_AFTER_LOCKED , 132and 133.Fn SRPL_REMOVE_LOCKED 134may be called during autoconf or from process context. 135An appropriate lock must be held that prevents concurrent modifications 136to the list. 137.Sh RETURN VALUES 138.Fn SRPL_FIRST_LOCKED , 139and 140.Fn SRPL_NEXT_LOCKED 141return a pointer to elements in the SRP list, or 142.Dv NULL 143if there are no more elements. 144.Pp 145.Fn SRPL_EMPTY_LOCKED 146returns non-zero when the list is empty, otherwise 0. 147.Sh SEE ALSO 148.Xr SRPL_FIRST 9 149.Sh HISTORY 150The srp API was originally written by 151.An Jonathan Matthew Aq Mt jmatthew@openbsd.org 152and 153.An David Gwynne Aq Mt dlg@openbsd.org . 154The SRP list API first appeared in 155.Ox 5.9 . 156