| epoch.9 (68195696a6e7bfd7e14e1ee20d69b48c97abd8fc) | epoch.9 (4619bce883aa504ef14c9db5419473cb20c8d1d8) |
|---|---|
| 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 --- 47 unchanged lines hidden (view full) --- 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)" 63.Ft int | 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 --- 47 unchanged lines hidden (view full) --- 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)" 63.Ft int |
| 64.Fn in_epoch "void" | 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 71Epochs are allocated with 72.Fn epoch_alloc --- 33 unchanged lines hidden (view full) --- 106The epoch API currently does not support sleeping in epoch_preempt sections. 107A caller should never call 108.Fn epoch_wait 109in the middle of an epoch section for the same epoch as this will lead to a deadlock. 110.Pp 111Be default mutexes cannot be held across 112.Fn epoch_wait_preempt . 113To permit this the epoch must be allocated with | 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 71Epochs are allocated with 72.Fn epoch_alloc --- 33 unchanged lines hidden (view full) --- 106The epoch API currently does not support sleeping in epoch_preempt sections. 107A caller should never call 108.Fn epoch_wait 109in the middle of an epoch section for the same epoch as this will lead to a deadlock. 110.Pp 111Be default mutexes cannot be held across 112.Fn epoch_wait_preempt . 113To permit this the epoch must be allocated with |
| 114.Fn EPOCH_LOCKED . | 114EPOCH_LOCKED. |
| 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. 123.Sh RETURN VALUES | 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. 123.Sh RETURN VALUES |
| 124.Fn in_epoch 125will return 1 if curthread is in an epoch, 0 otherwise. | 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 131prevented from leaving the section. 132Thus the wait time for the waiter is 133potentially unbounded. --- 64 unchanged lines hidden --- | 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 131prevented from leaving the section. 132Thus the wait time for the waiter is 133potentially unbounded. --- 64 unchanged lines hidden --- |