1.\" $OpenBSD: srp_enter.9,v 1.13 2016/06/07 14:37:46 jmc 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: June 7 2016 $ 18.Dt SRP_ENTER 9 19.Os 20.Sh NAME 21.Nm srp_init , 22.Nm srp_gc_init , 23.Nm srp_update , 24.Nm srp_update_locked , 25.Nm srp_swap , 26.Nm srp_swap_locked , 27.Nm srp_enter , 28.Nm srp_follow , 29.Nm srp_leave , 30.Nm srp_get_locked , 31.Nm srp_finalize , 32.Nm srp_gc_finalize , 33.Nm SRP_INITIALIZER , 34.Nm SRP_GC_INITIALIZER 35.Nd shared reference pointers 36.Sh SYNOPSIS 37.In sys/srp.h 38.Ft void 39.Fn srp_init "struct srp *p" 40.Ft void 41.Fo srp_gc_init 42.Fa "struct srp_gc *gc" 43.Fa "void (*dtor)(void *, void *)" 44.Fa "void *ctx" 45.Fc 46.Ft void * 47.Fn srp_swap "struct srp *p" "void *v" 48.Ft void * 49.Fn srp_swap_locked "struct srp *p" "void *v" 50.Ft void 51.Fn srp_update "struct srp_gc *gc" "struct srp *p" "void *v" 52.Ft void 53.Fn srp_update_locked "struct srp_gc *gc" "struct srp *p" "void *v" 54.Ft void * 55.Fn srp_enter "struct srp_ref *sr" "struct srp *p" 56.Ft void * 57.Fn srp_follow "struct srp_ref *sr" "struct srp *n" 58.Ft void 59.Fn srp_leave "struct srp_ref *sr" 60.Ft void * 61.Fn srp_get_locked "struct srp *p" 62.Ft void 63.Fn srp_finalize "void *v" 64.Ft void 65.Fn srp_gc_finalize "struct srp_gc *gc" 66.Fn SRP_INITIALIZER 67.Fo SRP_GC_INITIALIZER 68.Fa "void (*dtor)(void *, void *)" 69.Fa "void *ctx" 70.Fc 71.Sh DESCRIPTION 72An 73srp 74structure represents a pointer or reference to an object in memory. 75The 76srp 77API provides concurrent lock free access to these objects, and can 78guarantee that the data isn't destroyed while that reference is in 79use. 80It does not prevent concurrent modification of the referenced object. 81.Pp 82.Fn srp_init 83initialises the srp structure 84.Fa p 85to an empty state. 86.Pp 87.Fn srp_gc_init 88initialises the srp_gc structure 89.Fa gc 90so it can be used as a garbage collector for data that gets referenced by srp 91structures. 92An update to an srp structure will cause the old data to be destroyed when it 93is no longer referenced by any CPU in the system. 94The old data will be destroyed by the garbage collector by a call to 95.Fa dtor 96with 97.Fa ctx 98as the first argument and the pointer to the data as the second argument. 99.Pp 100.Fn srp_update 101and 102.Fn srp_update_locked 103replace the data referenced by the srp struct 104.Fa p 105with the data referenced by 106.Fa v . 107When the original data is no longer in use it will be destroyed by the garbage 108collector 109.Fa gc . 110.Fn srp_update 111uses atomic CPU operations to change the references. 112.Fn srp_update_locked 113may be used if modifications to 114.Fa p 115are already serialised by the caller. 116Both 117.Fn srp_update 118and 119.Fn srp_update_locked 120may sleep. 121.Pp 122.Fn srp_swap 123and 124.Fn srp_swap_locked 125replace the data referenced by the srp struct 126.Fa p 127with the data referenced by 128.Fa v . 129When clearing or replacing the last reference to a data structure, 130.Fn srp_finalize 131must be used to ensure that the data is longer in use via any srp structures. 132.Fn srp_swap 133uses atomic CPU operations to change the reference. 134.Fn srp_update_locked 135may be used if modifications to 136.Fa p 137are already serialised by the caller. 138.Pp 139.Fn srp_enter 140returns a pointer to a data structure referenced by the srp struct 141.Fa p 142and guarantees it will remain available for use until it is released with a 143call to 144.Fn srp_leave 145or 146.Fn srp_follow . 147The reference is held via 148.Fa sr . 149.Pp 150.Fn srp_follow 151replaces the reference held via 152.Fa sr 153with a reference to the data structure represented by 154.Fa p . 155.Pp 156.Fn srp_leave 157releases the reference held via 158.Fa sr 159and makes it available for garbage collection. 160.Pp 161.Fn srp_get_locked 162provides access to the data referenced by the srp 163.Fa p 164if the caller has excluded updates to 165.Fa p . 166.Pp 167.Fn srp_finalize 168sleeps until there are no longer any references to 169.Fa v 170via any srp structure in the system. 171.Pp 172.Fn srp_gc_finalize 173sleeps until all references to data by srp structures using the 174garbage collector 175.Fa gc 176have completed. 177That in turn means the 178.Fa gc 179structure will no longer be referenced and can itself be destroyed. 180.Pp 181A srp structure declaration can be initialised with the 182.Fn SRP_INITIALIZER 183macro. 184.Pp 185A srp_gc structure declaration can be initialised with the 186.Fn SRP_GC_INITIALIZER 187macro. 188Data will be destroyed by the garbage collector by a call to 189.Fa dtor 190with 191.Fa ctx 192as the first argument and the pointer to the data as the second argument. 193.Sh CONTEXT 194.Fn srp_init , 195.Fn srp_gc_init , 196.Fn srp_update , 197.Fn srp_update_locked , 198.Fn srp_get_locked , 199.Fn srp_finalize , 200and 201.Fn srp_gc_finalize 202can be called during autoconf or from process context. 203.Pp 204.Fn srp_swap , 205.Fn srp_swap_locked , 206.Fn srp_enter , 207.Fn srp_follow , 208and 209.Fn srp_leave 210can be called during autoconf, from process context, or from interrupt context. 211.Sh RETURN VALUES 212.Fn srp_swap 213and 214.Fn srp_swap_locked 215return a pointer to the previous value referenced by the srp structure 216.Fa p . 217.Pp 218.Fn srp_enter , 219.Fn srp_follow , 220and 221.Fn srp_get_locked 222return a pointer to the data referenced by the srp structure 223.Fa p 224or 225.Dv NULL . 226.Sh HISTORY 227The srp API was originally written by 228.An Jonathan Matthew Aq Mt jmatthew@openbsd.org 229and 230.An David Gwynne Aq Mt dlg@openbsd.org . 231The srp API first appeared in 232.Ox 5.8 . 233