.\"	$OpenBSD: srp_enter.9,v 1.4 2015/09/01 03:47:58 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: September 1 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_follow ,
.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_follow" "struct srp *p" "void *v" "struct srp *n"
.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 it is released with a
call to
.Fn srp_leave
or
.Fn srp_follow .
.Pp
.Fn srp_follow
returns a pointer to the data structure referenced by the srp struct
.Fa n
that exists within the structure referenced by
.Fa v
via
.Fa p ,
while releasing the reference to
.Fa v
and making it available for garbage collection.
It is equivalent to a call to
.Fn srp_enter
using
.Fa n
as an argument
followed by a call to
.Fn srp_leave
with
.Fa p
and
.Fa v
as arguments.
.Fn 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.
.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 ,
.Fn srp_follow ,
and
.Fn srp_leave
can be called during autoconf, from process context, or from interrupt context.
Calling
.Fn srp_follow
or
.Fn srp_leave
from a different context or on a different CPU to the preceding
.Fn srp_enter
or
.Fn srp_follow
calls will lead to undefined behaviour.
.Pp
SRP critical sections must be released with
.Fn srp_leave
in the opposite order in which they were taken with
.Fn srp_enter
unless a critical section is exchanged with
.Fn srp_follow .
.Sh RETURN VALUES
.Fn srp_enter ,
.Fn srp_follow ,
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 .