| epoch.9 (2a22df74e9fceaffd62ee437de08383d6cf8cfe0) | epoch.9 (131b2b7658d7e961a245697cb5af55306388fc54) |
|---|---|
| 1.\" 2.\" Copyright (C) 2018 Matthew Macy <mmacy@FreeBSD.org>. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice(s), this list of conditions and the following disclaimer as --- 12 unchanged lines hidden (view full) --- 21.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 22.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 25.\" DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" | 1.\" 2.\" Copyright (C) 2018 Matthew Macy <mmacy@FreeBSD.org>. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice(s), this list of conditions and the following disclaimer as --- 12 unchanged lines hidden (view full) --- 21.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 22.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 25.\" DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" |
| 29.Dd June 25, 2018 | 29.Dd June 28, 2019 |
| 30.Dt EPOCH 9 31.Os 32.Sh NAME 33.Nm epoch , 34.Nm epoch_context , 35.Nm epoch_alloc , 36.Nm epoch_free , 37.Nm epoch_enter , 38.Nm epoch_exit , 39.Nm epoch_wait , 40.Nm epoch_call , | 30.Dt EPOCH 9 31.Os 32.Sh NAME 33.Nm epoch , 34.Nm epoch_context , 35.Nm epoch_alloc , 36.Nm epoch_free , 37.Nm epoch_enter , 38.Nm epoch_exit , 39.Nm epoch_wait , 40.Nm epoch_call , |
| 41.Nm epoch_drain_callbacks , |
|
| 41.Nm in_epoch , 42.Nd kernel epoch based reclamation 43.Sh SYNOPSIS 44.In sys/param.h 45.In sys/proc.h 46.In sys/epoch.h 47.Ft epoch_t 48.Fn epoch_alloc "int flags" --- 6 unchanged lines hidden (view full) --- 55.Ft void 56.Fn epoch_exit_preempt "epoch_t epoch" "epoch_tracker_t et" 57.Ft void 58.Fn epoch_wait "epoch_t epoch" 59.Ft void 60.Fn epoch_wait_preempt "epoch_t epoch" 61.Ft void 62.Fn epoch_call "epoch_t epoch" "epoch_context_t ctx" "void (*callback) (epoch_context_t)" | 42.Nm in_epoch , 43.Nd kernel epoch based reclamation 44.Sh SYNOPSIS 45.In sys/param.h 46.In sys/proc.h 47.In sys/epoch.h 48.Ft epoch_t 49.Fn epoch_alloc "int flags" --- 6 unchanged lines hidden (view full) --- 56.Ft void 57.Fn epoch_exit_preempt "epoch_t epoch" "epoch_tracker_t et" 58.Ft void 59.Fn epoch_wait "epoch_t epoch" 60.Ft void 61.Fn epoch_wait_preempt "epoch_t epoch" 62.Ft void 63.Fn epoch_call "epoch_t epoch" "epoch_context_t ctx" "void (*callback) (epoch_context_t)" |
| 64.Ft void 65.Fn epoch_drain_callbacks "epoch_t epoch" |
|
| 63.Ft int 64.Fn in_epoch "epoch_t epoch" 65.Sh DESCRIPTION 66Epochs are used to guarantee liveness and immutability of data by 67deferring reclamation and mutation until a grace period has elapsed. 68Epochs do not have any lock ordering issues. 69Entering and leaving an epoch section will never block. 70.Pp --- 44 unchanged lines hidden (view full) --- 115When doing this one must be cautious of creating a situation where a deadlock is 116possible. Note that epochs are not a straight replacement for read locks. 117Callers must use safe list and tailq traversal routines in an epoch (see ck_queue). 118When modifying a list referenced from an epoch section safe removal 119routines must be used and the caller can no longer modify a list entry 120in place. 121An item to be modified must be handled with copy on write 122and frees must be deferred until after a grace period has elapsed. | 66.Ft int 67.Fn in_epoch "epoch_t epoch" 68.Sh DESCRIPTION 69Epochs are used to guarantee liveness and immutability of data by 70deferring reclamation and mutation until a grace period has elapsed. 71Epochs do not have any lock ordering issues. 72Entering and leaving an epoch section will never block. 73.Pp --- 44 unchanged lines hidden (view full) --- 118When doing this one must be cautious of creating a situation where a deadlock is 119possible. Note that epochs are not a straight replacement for read locks. 120Callers must use safe list and tailq traversal routines in an epoch (see ck_queue). 121When modifying a list referenced from an epoch section safe removal 122routines must be used and the caller can no longer modify a list entry 123in place. 124An item to be modified must be handled with copy on write 125and frees must be deferred until after a grace period has elapsed. |
| 126.Pp 127The 128.Fn epoch_drain_callbacks 129function is used to drain all pending callbacks which have been invoked by prior 130.Fn epoch_call 131function calls on the same epoch. 132This function is useful when there are shared memory structure(s) 133referred to by the epoch callback(s) which are not refcounted and are 134rarely freed. 135The typical place for calling this function is right before freeing or 136invalidating the shared resource(s) used by the epoch callback(s). 137This function can sleep and is not optimized for performance. |
|
| 123.Sh RETURN VALUES 124.Fn in_epoch curepoch 125will return 1 if curthread is in curepoch, 0 otherwise. 126.Sh CAVEATS 127One must be cautious when using 128.Fn epoch_wait_preempt 129threads are pinned during epoch sections so if a thread in a section is then 130preempted by a higher priority compute bound thread on that CPU it can be --- 71 unchanged lines hidden --- | 138.Sh RETURN VALUES 139.Fn in_epoch curepoch 140will return 1 if curthread is in curepoch, 0 otherwise. 141.Sh CAVEATS 142One must be cautious when using 143.Fn epoch_wait_preempt 144threads are pinned during epoch sections so if a thread in a section is then 145preempted by a higher priority compute bound thread on that CPU it can be --- 71 unchanged lines hidden --- |