SRP_ENTER(9) | Kernel Developer's Manual | SRP_ENTER(9) |
srp_init
,
srp_gc_init
, srp_update
,
srp_update_locked
, srp_swap
,
srp_swap_locked
, srp_enter
,
srp_follow
, srp_leave
,
srp_get_locked
,
srp_finalize
,
srp_gc_finalize
,
SRP_INITIALIZER
,
SRP_GC_INITIALIZER
— shared
reference pointers
#include
<sys/srp.h>
void
srp_init
(struct
srp *p);
void
srp_gc_init
(struct srp_gc *gc,
void (*dtor)(void *, void *), void
*ctx);
void *
srp_swap
(struct
srp *p, void
*v);
void *
srp_swap_locked
(struct
srp *p, void
*v);
void
srp_update
(struct
srp_gc *gc, struct srp
*p, void *v);
void
srp_update_locked
(struct
srp_gc *gc, struct srp
*p, void *v);
void *
srp_enter
(struct
srp_ref *sr, struct srp
*p);
void *
srp_follow
(struct
srp_ref *sr, struct srp
*n);
void
srp_leave
(struct
srp_ref *sr);
void *
srp_get_locked
(struct
srp *p);
void
srp_finalize
(void
*v);
void
srp_gc_finalize
(struct
srp_gc *gc);
SRP_INITIALIZER
();
SRP_GC_INITIALIZER
(void
(*dtor)(void *, void *), void *ctx);
An srp structure represents a pointer or reference to an object in memory. The srp API provides concurrent lock free access to these objects, and can guarantee that the data isn't destroyed while that reference is in use. It does not prevent concurrent modification of the referenced object.
srp_init
() initialises the srp structure
p to an empty state.
srp_gc_init
() initialises the srp_gc
structure 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 dtor with
ctx as the first argument and the pointer to the data
as the second argument.
srp_update
() and
srp_update_locked
() replace the data referenced by
the srp struct p with the data referenced by
v. When the original data is no longer in use it will
be destroyed by the garbage collector gc.
srp_update
() uses atomic CPU operations to change
the references. srp_update_locked
() may be used if
modifications to p are already serialised by the
caller. Both srp_update
() and
srp_update_locked
() may sleep.
srp_swap
() and
srp_swap_locked
() replace the data referenced by the
srp struct p with the data referenced by
v. When clearing or replacing the last reference to a
data structure, srp_finalize
() must be used to
ensure that the data is no longer in use via any srp structures.
srp_swap
() uses atomic CPU operations to change the
reference. srp_swap_locked
() may be used if
modifications to p are already serialised by the
caller.
srp_enter
() returns a pointer to a data
structure referenced by the srp struct p and
guarantees it will remain available for use until it is released with a call
to srp_leave
() or
srp_follow
(). The reference is held via
sr.
srp_follow
() replaces the reference held
via sr with a reference to the data structure
represented by p.
srp_leave
() releases the reference held
via sr and makes it available for garbage
collection.
srp_get_locked
() provides access to the
data referenced by the srp p if the caller has
excluded updates to p.
srp_finalize
() sleeps until there are no
longer any references to v via any srp structure in
the system.
srp_gc_finalize
() sleeps until all
references to data by srp structures using the garbage collector
gc have completed. That in turn means the
gc structure will no longer be referenced and can
itself be destroyed.
A srp structure declaration can be initialised with the
SRP_INITIALIZER
() macro.
A srp_gc structure declaration can be initialised with the
SRP_GC_INITIALIZER
() macro. Data will be destroyed
by the garbage collector by a call to dtor with
ctx as the first argument and the pointer to the data
as the second argument.
srp_init
(),
srp_gc_init
(), srp_update
(),
srp_update_locked
(),
srp_get_locked
(),
srp_finalize
(), and
srp_gc_finalize
() can be called during autoconf or
from process context.
srp_swap
(),
srp_swap_locked
(),
srp_enter
(), srp_follow
(),
and srp_leave
() can be called during autoconf, from
process context, or from interrupt context.
srp_swap
() and
srp_swap_locked
() return a pointer to the previous
value referenced by the srp structure p.
srp_enter
(),
srp_follow
(), and
srp_get_locked
() return a pointer to the data
referenced by the srp structure p or
NULL
.
The srp API was originally written by Jonathan Matthew <jmatthew@openbsd.org> and David Gwynne <dlg@openbsd.org>. The srp API first appeared in OpenBSD 5.8.
January 18, 2017 | OpenBSD-current |