SRP_ENTER(9) FreeBSD Kernel Developer's Manual SRP_ENTER(9)
NAME
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
SYNOPSIS
#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, const char *wmesg);
void
srp_gc_finalize(struct srp_gc *gc);
SRP_INITIALIZER();
SRP_GC_INITIALIZER(void (*dtor)(void *, void *), void *ctx);
DESCRIPTION
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.
CONTEXT
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.
RETURN VALUES
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.
HISTORY
The srp API was originally written by Jonathan Matthew
<
[email protected]> and David Gwynne <
[email protected]>. The srp API
first appeared in OpenBSD 5.8.
FreeBSD 14.1-RELEASE-p8 July 27, 2022 FreeBSD 14.1-RELEASE-p8