1.\" $OpenBSD: srp_enter.9,v 1.17 2022/07/27 17:05:56 bluhm 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: July 27 2022 $ 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" "const char *wmesg" 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 no longer in use via any srp 132structures. 133.Fn srp_swap 134uses atomic CPU operations to change the reference. 135.Fn srp_swap_locked 136may be used if modifications to 137.Fa p 138are already serialised by the caller. 139.Pp 140.Fn srp_enter 141returns a pointer to a data structure referenced by the srp struct 142.Fa p 143and guarantees it will remain available for use until it is released with a 144call to 145.Fn srp_leave 146or 147.Fn srp_follow . 148The reference is held via 149.Fa sr . 150.Pp 151.Fn srp_follow 152replaces the reference held via 153.Fa sr 154with a reference to the data structure represented by 155.Fa p . 156.Pp 157.Fn srp_leave 158releases the reference held via 159.Fa sr 160and makes it available for garbage collection. 161.Pp 162.Fn srp_get_locked 163provides access to the data referenced by the srp 164.Fa p 165if the caller has excluded updates to 166.Fa p . 167.Pp 168.Fn srp_finalize 169sleeps until there are no longer any references to 170.Fa v 171via any srp structure in the system. 172.Pp 173.Fn srp_gc_finalize 174sleeps until all references to data by srp structures using the 175garbage collector 176.Fa gc 177have completed. 178That in turn means the 179.Fa gc 180structure will no longer be referenced and can itself be destroyed. 181.Pp 182A srp structure declaration can be initialised with the 183.Fn SRP_INITIALIZER 184macro. 185.Pp 186A srp_gc structure declaration can be initialised with the 187.Fn SRP_GC_INITIALIZER 188macro. 189Data will be destroyed by the garbage collector by a call to 190.Fa dtor 191with 192.Fa ctx 193as the first argument and the pointer to the data as the second argument. 194.Sh CONTEXT 195.Fn srp_init , 196.Fn srp_gc_init , 197.Fn srp_update , 198.Fn srp_update_locked , 199.Fn srp_get_locked , 200.Fn srp_finalize , 201and 202.Fn srp_gc_finalize 203can be called during autoconf or from process context. 204.Pp 205.Fn srp_swap , 206.Fn srp_swap_locked , 207.Fn srp_enter , 208.Fn srp_follow , 209and 210.Fn srp_leave 211can be called during autoconf, from process context, or from interrupt context. 212.Sh RETURN VALUES 213.Fn srp_swap 214and 215.Fn srp_swap_locked 216return a pointer to the previous value referenced by the srp structure 217.Fa p . 218.Pp 219.Fn srp_enter , 220.Fn srp_follow , 221and 222.Fn srp_get_locked 223return a pointer to the data referenced by the srp structure 224.Fa p 225or 226.Dv NULL . 227.Sh HISTORY 228The srp API was originally written by 229.An Jonathan Matthew Aq Mt jmatthew@openbsd.org 230and 231.An David Gwynne Aq Mt dlg@openbsd.org . 232The srp API first appeared in 233.Ox 5.8 . 234