Differential D20109 Diff 59152 head/share/man/man9/epoch.9

Changeset View

Standalone View

head/share/man/man9/epoch.9

	Show All 20 Lines
	.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER			.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
	.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
	.\" DAMAGE.			.\" DAMAGE.
	.\"			.\"
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd June 25, 2018			.Dd June 28, 2019
	.Dt EPOCH 9			.Dt EPOCH 9
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm epoch ,			.Nm epoch ,
	.Nm epoch_context ,			.Nm epoch_context ,
	.Nm epoch_alloc ,			.Nm epoch_alloc ,
	.Nm epoch_free ,			.Nm epoch_free ,
	.Nm epoch_enter ,			.Nm epoch_enter ,
	.Nm epoch_exit ,			.Nm epoch_exit ,
	.Nm epoch_wait ,			.Nm epoch_wait ,
	.Nm epoch_call ,			.Nm epoch_call ,
				.Nm epoch_drain_callbacks ,
	.Nm in_epoch ,			.Nm in_epoch ,
	.Nd kernel epoch based reclamation			.Nd kernel epoch based reclamation
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.In sys/param.h			.In sys/param.h
	.In sys/proc.h			.In sys/proc.h
	.In sys/epoch.h			.In sys/epoch.h
	.Ft epoch_t			.Ft epoch_t
	.Fn epoch_alloc "int flags"			.Fn epoch_alloc "int flags"
	.Ft void			.Ft void
	.Fn epoch_enter "epoch_t epoch"			.Fn epoch_enter "epoch_t epoch"
	.Ft void			.Ft void
	.Fn epoch_enter_preempt "epoch_t epoch" "epoch_tracker_t et"			.Fn epoch_enter_preempt "epoch_t epoch" "epoch_tracker_t et"
	.Ft void			.Ft void
	.Fn epoch_exit "epoch_t epoch"			.Fn epoch_exit "epoch_t epoch"
	.Ft void			.Ft void
	.Fn epoch_exit_preempt "epoch_t epoch" "epoch_tracker_t et"			.Fn epoch_exit_preempt "epoch_t epoch" "epoch_tracker_t et"
	.Ft void			.Ft void
	.Fn epoch_wait "epoch_t epoch"			.Fn epoch_wait "epoch_t epoch"
	.Ft void			.Ft void
	.Fn epoch_wait_preempt "epoch_t epoch"			.Fn epoch_wait_preempt "epoch_t epoch"
	.Ft void			.Ft void
	.Fn epoch_call "epoch_t epoch" "epoch_context_t ctx" "void (*callback) (epoch_context_t)"			.Fn epoch_call "epoch_t epoch" "epoch_context_t ctx" "void (*callback) (epoch_context_t)"
				.Ft void
				.Fn epoch_drain_callbacks "epoch_t epoch"
	.Ft int			.Ft int
	.Fn in_epoch "epoch_t epoch"			.Fn in_epoch "epoch_t epoch"
	.Sh DESCRIPTION			.Sh DESCRIPTION
	Epochs are used to guarantee liveness and immutability of data by			Epochs are used to guarantee liveness and immutability of data by
	deferring reclamation and mutation until a grace period has elapsed.			deferring reclamation and mutation until a grace period has elapsed.
	Epochs do not have any lock ordering issues.			Epochs do not have any lock ordering issues.
	Entering and leaving an epoch section will never block.			Entering and leaving an epoch section will never block.
	.Pp			.Pp
	▲ Show 20 Lines • Show All 44 Lines • ▼ Show 20 Lines
	When doing this one must be cautious of creating a situation where a deadlock is			When doing this one must be cautious of creating a situation where a deadlock is
	possible. Note that epochs are not a straight replacement for read locks.			possible. Note that epochs are not a straight replacement for read locks.
	Callers must use safe list and tailq traversal routines in an epoch (see ck_queue).			Callers must use safe list and tailq traversal routines in an epoch (see ck_queue).
	When modifying a list referenced from an epoch section safe removal			When modifying a list referenced from an epoch section safe removal
	routines must be used and the caller can no longer modify a list entry			routines must be used and the caller can no longer modify a list entry
	in place.			in place.
	An item to be modified must be handled with copy on write			An item to be modified must be handled with copy on write
	and frees must be deferred until after a grace period has elapsed.			and frees must be deferred until after a grace period has elapsed.
				.Pp
				The
				.Fn epoch_drain_callbacks
				function is used to drain all pending callbacks which have been invoked by prior
				.Fn epoch_call
				function calls on the same epoch.
				This function is useful when there are shared memory structure(s)
				referred to by the epoch callback(s) which are not refcounted and are
				rarely freed.
				The typical place for calling this function is right before freeing or
				invalidating the shared resource(s) used by the epoch callback(s).
				This function can sleep and is not optimized for performance.
	.Sh RETURN VALUES			.Sh RETURN VALUES
	.Fn in_epoch curepoch			.Fn in_epoch curepoch
	will return 1 if curthread is in curepoch, 0 otherwise.			will return 1 if curthread is in curepoch, 0 otherwise.
	.Sh CAVEATS			.Sh CAVEATS
	One must be cautious when using			One must be cautious when using
	.Fn epoch_wait_preempt			.Fn epoch_wait_preempt
	threads are pinned during epoch sections so if a thread in a section is then			threads are pinned during epoch sections so if a thread in a section is then
	preempted by a higher priority compute bound thread on that CPU it can be			preempted by a higher priority compute bound thread on that CPU it can be
	▲ Show 20 Lines • Show All 71 Lines • Show Last 20 Lines