SRP_ENTER(9)

NAME
srp_init, srp_gc_init, srp_update, srp_update_locked, srp_enter, srp_follow, srp_leave, srp_get_locked, srp_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_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 *p);
void *
srp_follow(struct srp *p, void *v, struct srp *n);
void
srp_leave(struct srp *p, void *v);
void *
srp_get_locked(struct srp *p);
void
srp_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_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().

srp_follow() returns a pointer to the data structure referenced by the srp struct n that exists within the structure referenced by v via p, while releasing the reference to v and making it available for garbage collection. It is equivalent to a call to srp_enter() using n as an argument followed by a call to srp_leave() with p and v as arguments. srp_follow() is necessary to correctly order the taking and releasing of SRP critical sections in situations such as following a chain of data structures linked with SRPs.

srp_leave() releases the reference to v by the srp struct p 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 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(), and srp_finalize() can be called during autoconf, or from process context.

srp_enter(), srp_follow(), and srp_leave() can be called during autoconf, from process context, or from interrupt context. Calling srp_follow() or srp_leave() from a different context or on a different CPU to the preceding srp_enter() or srp_follow() calls will lead to undefined behaviour.

SRP critical sections must be released with srp_leave() in the opposite order in which they were taken with srp_enter() unless a critical section is exchanged with srp_follow().

RETURN VALUES
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 <jmatthew@openbsd.org> and David Gwynne <dlg@openbsd.org>. The srp API first appeared in OpenBSD 5.8.