1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
.\" $OpenBSD: srp_enter.9,v 1.3 2015/08/14 05:18:50 dlg Exp $
.\"
.\" Copyright (c) 2015 David Gwynne <dlg@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: August 14 2015 $
.Dt SRP_ENTER 9
.Os
.Sh NAME
.Nm srp_init ,
.Nm srp_gc_init ,
.Nm srp_update ,
.Nm srp_update_locked ,
.Nm srp_enter ,
.Nm srp_leave ,
.Nm srp_get_locked ,
.Nm srp_finalize ,
.Nm SRP_INITIALIZER ,
.Nm SRP_GC_INITIALIZER
.Nd shared reference pointers
.Sh SYNOPSIS
.In sys/srp.h
.Ft void
.Fn "srp_init" "struct srp *p"
.Ft void
.Fo "srp_gc_init"
.Fa "struct srp_gc *gc"
.Fa "void (*dtor)(void *, void *)"
.Fa "void *ctx"
.Fc
.Ft void
.Fn "srp_update" "struct srp_gc *gc" "struct srp *p" "void *v"
.Ft void
.Fn "srp_update_locked" "struct srp_gc *gc" "struct srp *p" "void *v"
.Ft void *
.Fn "srp_enter" "struct srp *p"
.Ft void
.Fn "srp_leave" "struct srp *p" "void *v"
.Ft void *
.Fn "srp_get_locked" "struct srp *p"
.Ft void
.Fn "srp_finalize" "struct srp_gc *gc"
.Fn "SRP_INITIALIZER"
.Fo "SRP_GC_INITIALIZER"
.Fa "void (*dtor)(void *, void *)"
.Fa "void *ctx"
.Fc
.Sh DESCRIPTION
The
srp
API provides concurrent lock free access to data structures and guarantees the
data isn't destroyed while it is in use.
.Pp
.Fn srp_init
initialises the srp structure
.Fa p
to an empty state.
.Pp
.Fn srp_gc_init
initialises the srp_gc structure
.Fa gc
so it can be used as a garbage collector for data that gets referenced by srp
structures.
An update to an srp structure will cause the old data to be destroyed when it
is no longer referenced by any CPU in the system.
The old data will be destroyed by the garbage collector by a call to
.Fa dtor
with
.Fa ctx
as the first argument and the pointer to the data as the second argument.
.Pp
.Fn srp_update
and
.Fn srp_update_locked
replace the data referenced by the srp struct
.Fa p
with the data referenced by
.Fa v .
When the original data is no longer in use it will be destroyed by the garbage
collector
.Fa gc .
.Fn srp_update
uses atomic CPU operations to change the references.
.Fn srp_update_locked
may be used if modifications to
.Fa p
are already serialised by the caller.
.Pp
.Fn srp_enter
returns a pointer to a data structure referenced by the srp struct
.Fa p
and guarantees it will remain available for use until a call to
.Fn srp_leave .
.Pp
.Fn srp_leave
releases the reference to
.Fa v
by the srp struct
.Fa p
and makes it available for garbage collection.
.Pp
.Fn srp_get_locked
provides access to the data referenced by the srp
.Fa p
if the caller has excluded updates to
.Fa p .
.Pp
.Fn srp_finalize
sleeps until all references to data by srp structures using the
garbage collector
.Fa gc
have completed.
That in turn means the
.Fa gc
structure will no longer be referenced and can itself be destroyed.
.Pp
A srp structure declaraction can be initialised with the
.Fn SRP_INITIALIZER
macro.
.Pp
A srp_gc structure declaraction can be initialised with the
.Fn SRP_GC_INITIALIZER
macro.
Data will be destroyed by the garbage collector by a call to
.Fa dtor
with
.Fa ctx
as the first argument and the pointer to the data as the second argument.
.Sh CONTEXT
.Fn srp_init ,
.Fn srp_gc_init ,
.Fn srp_update ,
.Fn srp_update_locked ,
.Fn srp_update_get_locked ,
and
.Fn srp_finalize
can be called during autoconf, or from process context.
.Pp
.Fn srp_enter
and
.Fn srp_leave
can be called during autoconf, from process context, or from interrupt context.
Calling
.Fn srp_leave
from a different context or on a different CPU to the preceding
.Fn srp_enter
call will lead to undefined behaviour.
.Sh RETURN VALUES
.Fn srp_enter
and
.Fn srp_get_locked
returns a pointer to the data referenced by the srp structure
.Fa p
or
.Dv NULL .
.Sh HISTORY
The srp API was originally written by
.An Jonathan Matthew Aq Mt jmatthew@openbsd.org
and
.An David Gwynne Aq Mt dlg@openbsd.org .
The srp API first appeared in
.Ox 5.8 .
|
