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

July 27, 2022 | Debian