1.\" $OpenBSD: SRPL_EMPTY_LOCKED.9,v 1.1 2016/11/20 12:05:25 mpi 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 20 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 singly-linked shared reference pointer list 30.Sh SYNOPSIS 31.In sys/srp.h 32.Fn "SRPL_EMPTY_LOCKED" "SRPL_HEAD *sl" 33.Ft void * 34.Fn "SRPL_FIRST_LOCKED" "SRPL_HEAD *sl" 35.Ft void * 36.Fn "SRPL_NEXT_LOCKED" "struct TYPE *listelm" "FIELDNAME" 37.Fn "SRPL_FOREACH_LOCKED" "VARNAME" "SRPL_HEAD *sl" "FIELDNAME" 38.Fn "SRPL_FOREACH_SAFE_LOCKED" "VARNAME" "SRPL_HEAD *sl" "FIELDNAME" "TEMP_VARNAME" 39.Fo "SRPL_INSERT_HEAD_LOCKED" 40.Fa "struct srpl_rc *rc" 41.Fa "SRPL_HEAD *sl" 42.Fa "struct TYPE *elm" 43.Fa "FIELDNAME" 44.Fc 45.Fo "SRPL_INSERT_AFTER_LOCKED" 46.Fa "struct srpl_rc *rc" 47.Fa "struct TYPE *listelm" 48.Fa "struct TYPE *elm" 49.Fa "FIELDNAME" 50.Fc 51.Fo "SRPL_REMOVE_LOCKED" 52.Fa "struct srpl_rc *rc" 53.Fa "SRPL_HEAD *sl" 54.Fa "struct TYPE *listelm" 55.Fa "TYPE" 56.Fa "FIELDNAME" 57.Fc 58.Sh DESCRIPTION 59The SRP list 60macros build a linked list on top of shared reference pointers. 61This allows concurrent traversal of a linked list and access to the 62items on the list. 63.Pp 64.Fn SRPL_EMPTY_LOCKED 65tests whether the SRP list 66.Fa sl 67is empty. 68.Pp 69.Fn SRPL_FIRST_LOCKED 70accesses the first element in the SRP list 71.Fa sl . 72.Pp 73.Fn SRPL_NEXT_LOCKED 74accesses the next element in the SRP list after 75.Fa listelm . 76.Pp 77.Fn SRPL_FOREACH_LOCKED 78creates a loop for traversing the elements in the SRP list 79.Fa sl . 80.Pp 81.Fn SRPL_FOREACH_SAFE_LOCKED 82creates a loop for traversing the elements in the SRP list 83.Fa sl , 84permitting it to remove 85.Fa VARNAME 86as well as freeing it from within the loop safely without interfering with the 87traversal. 88.Pp 89.Fn SRPL_INSERT_HEAD_LOCKED 90inserts 91.Fa elm 92into the SRP list 93.Fa sl . 94Reference counts are adjusted on the list items using the functions 95specified by 96.Fa rc . 97.Pp 98.Fn SRPL_INSERT_AFTER_LOCKED 99inserts 100.Fa elm 101into an SRP list after the element 102.Fa listelm . 103Reference counts are adjusted on the list items using the functions 104specified by 105.Fa rc . 106.Pp 107.Fn SRPL_REMOVE_LOCKED 108iterates over the SRP list 109.Fa sl 110until it finds 111.Fa listelm 112and then removes it. 113Reference counts are adjusted on the list items using the functions 114specified by 115.Fa rc . 116.Sh CONTEXT 117.Fn SRPL_EMPTY_LOCKED , 118.Fn SRPL_FIRST_LOCKED , 119.Fn SRPL_NEXT_LOCKED , 120.Fn SRPL_FOREACH_LOCKED , 121.Fn SRPL_INSERT_HEAD_LOCKED , 122.Fn SRPL_INSERT_AFTER_LOCKED , 123and 124.Fn SRPL_REMOVE_LOCKED 125may be called during autoconf or from process context. 126An appropriate lock must be held that prevents concurrent modifications 127to the list. 128.Sh RETURN VALUES 129.Fn SRPL_FIRST_LOCKED , 130and 131.Fn SRPL_NEXT_LOCKED 132return a pointer to elements in the SRP list, or 133.Dv NULL 134if there are no more elements. 135.Pp 136.Fn SRPL_EMPTY_LOCKED 137returns non-zero when the list is empty, otherwise 0. 138.Sh HISTORY 139The srp API was originally written by 140.An Jonathan Matthew Aq Mt jmatthew@openbsd.org 141and 142.An David Gwynne Aq Mt dlg@openbsd.org . 143The SRP list API first appeared in 144.Ox 5.9 . 145