1.\" $OpenBSD: srpl_rc_init.9,v 1.14 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_RC_INIT 9 19.Os 20.Sh NAME 21.Nm srpl_rc_init , 22.Nm SRPL_HEAD , 23.Nm SRPL_ENTRY , 24.Nm SRPL_INIT , 25.Nm SRPL_FIRST , 26.Nm SRPL_NEXT , 27.Nm SRPL_FOLLOW , 28.Nm SRPL_FOREACH , 29.Nm SRPL_LEAVE , 30.Nm SRPL_RC_INITIALIZER 31.Nd singly-linked shared reference pointer list 32.Sh SYNOPSIS 33.In sys/srp.h 34.Vt struct srpl_rc; 35.Ft void 36.Fo "srpl_rc_init" 37.Fa "struct srpl_rc *rc" 38.Fa "void (*ref)(void *, void *)" 39.Fa "void (*unref)(void *, void *)" 40.Fa "void *ctx" 41.Fc 42.Fn SRPL_HEAD "HEADNAME" "TYPE" 43.Fn SRPL_ENTRY "TYPE" 44.Ft void 45.Fn "SRPL_INIT" "SRPL_HEAD *sl" 46.Ft void * 47.Fn "SRPL_FIRST" "struct srp_ref *sr" "SRPL_HEAD *sl" 48.Ft void * 49.Fn "SRPL_NEXT" "struct srp_ref *sr" "struct TYPE *listelm" "FIELDNAME" 50.Ft void * 51.Fn "SRPL_FOLLOW" "struct srp_ref *sr" "struct TYPE *listelm" "FIELDNAME" 52.Fo "SRPL_FOREACH" 53.Fa "VARNAME" 54.Fa "struct srp_ref *sr" 55.Fa "SRPL_HEAD *sl" 56.Fa "FIELDNAME" 57.Fc 58.Ft void 59.Fn "SRPL_LEAVE" "struct srp_ref *sr" 60.Fo "SRPL_RC_INITIALIZER" 61.Fa "void (*ref)(void *, void *)" 62.Fa "void (*unref)(void *, void *)" 63.Fa "void *ctx" 64.Fc 65.Sh DESCRIPTION 66The SRPL list 67macros build a linked list on top of shared reference pointers. 68This allows concurrent traversal of a linked list and access to the 69items on the list. 70.Pp 71SRP lists are a generic type represented by a 72.Vt SRPL_HEAD . 73The elements inserted into the list must be structures that contain a 74.Vt SRPL_ENTRY 75field. 76Further, the elements must also support reference counting as 77insertion and removal operations can cause items to be temporarily 78referenced by multiple SRPs within the list at the same time. 79.Pp 80.Fn srpl_rc_init 81initialises the SRP list refcounts 82.Fa rc 83structure so it can be used to manage the reference counts on 84elements in the list. 85The insertion or removal of an element in an SRP list will increment 86the reference counts on elements within the list via calls to 87.Fa ref . 88As these references are released by the SRP infrastructure, the 89reference counts will be decremented by calls to 90.Fa unref . 91.Fa unref 92is also responsible for freeing the element when the reference count 93reaches 0. 94Both 95.Fa ref 96and 97.Fa unref 98will be called with 99.Fa ctx 100as their first argument and a pointer to the element as their second 101argument. 102.Pp 103.Fn SRPL_INIT 104initialises the SRP list 105.Fa sl 106to an empty state. 107.Pp 108.Fn SRPL_FIRST 109accesses the first element in the SRP list 110.Fa sl 111and holds its reference via 112.Fa sr . 113.Pp 114.Fn SRPL_NEXT 115accesses the element in the SRP list after 116.Fa listelm 117and holds its reference via 118.Fa sr . 119.\".Pp 120.\"Every call to 121.\".Fn SRPL_FIRST 122.\"must have a corresponding call to 123.\".Fn SRPL_LEAVE 124.\"to release references to the list and its elements. 125.Pp 126.Fn SRPL_FOLLOW 127accesses the element in the SRP list after 128.Fa listelm 129and swaps the previous reference held via 130.Fa sr 131for the reference of the newly accessed item. 132.Pp 133.Fn SRPL_FOREACH 134creates a loop for traversing the list. 135Every call to 136.Fn SRPL_FOREACH 137must have a corresponding call to 138.Fn SRPL_LEAVE 139to release references to the list and its elements. 140.Pp 141.Fn SRPL_LEAVE 142releases references to the list and its elements held by previous 143calls to 144.Fn SRPL_FIRST , 145.Fn SRPL_NEXT , 146.Fn SRPL_FOLLOW , 147or 148.Fn SRPL_FOREACH . 149.Pp 150An srpl_rc declaration can be initialised with the 151.Fn SRPL_RC_INITIALIZER 152macro. 153.Sh CONTEXT 154.Fn SRPL_INIT , 155.Fn SRPL_FIRST , 156.Fn SRPL_NEXT , 157.Fn SRPL_FOLLOW , 158.Fn SRPL_FOREACH , 159and 160.Fn SRPL_LEAVE 161may be called during autoconf, from process context, or from interrupt 162context. 163.Pp 164.Fn srpl_rc_init , 165may be called during autoconf or from process context. 166.Sh RETURN VALUES 167.Fn SRPL_FIRST , 168.Fn SRPL_NEXT , 169and 170.Fn SRPL_FOLLOW 171return a pointer to elements in the SRP list, or 172.Dv NULL 173if there are no more elements. 174.Sh SEE ALSO 175.Xr SRPL_FIRST_LOCKED 9 176.Sh HISTORY 177The srp API was originally written by 178.An Jonathan Matthew Aq Mt jmatthew@openbsd.org 179and 180.An David Gwynne Aq Mt dlg@openbsd.org . 181The SRP list API first appeared in 182.Ox 5.9 . 183