From 68195696a6e7bfd7e14e1ee20d69b48c97abd8fc Mon Sep 17 00:00:00 2001 From: Matt Macy Date: Wed, 4 Jul 2018 03:44:36 +0000 Subject: [PATCH] epoch(9): update man page for r335924 --- share/man/man9/epoch.9 | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/share/man/man9/epoch.9 b/share/man/man9/epoch.9 index 4acf68750689..e8ea339a422d 100644 --- a/share/man/man9/epoch.9 +++ b/share/man/man9/epoch.9 @@ -49,11 +49,11 @@ .Ft void .Fn epoch_enter "epoch_t epoch" .Ft void -.Fn epoch_enter_preempt "epoch_t epoch" +.Fn epoch_enter_preempt "epoch_t epoch" "epoch_tracker_t et" .Ft void .Fn epoch_exit "epoch_t epoch" .Ft void -.Fn epoch_exit_preempt "epoch_t epoch" +.Fn epoch_exit_preempt "epoch_t epoch" "epoch_tracker_t et" .Ft void .Fn epoch_wait "epoch_t epoch" .Ft void @@ -104,12 +104,16 @@ INVARIANTS can assert that a thread is in an epoch by using .Fn in_epoch . .Pp The epoch API currently does not support sleeping in epoch_preempt sections. -A caller cannot do epoch_enter recursively on different preemptible epochs. A caller should never call .Fn epoch_wait -in the middle of an epoch section as this will lead to a deadlock. +in the middle of an epoch section for the same epoch as this will lead to a deadlock. .Pp -Note that epochs are not a straight replacement for read locks. +Be default mutexes cannot be held across +.Fn epoch_wait_preempt . +To permit this the epoch must be allocated with +.Fn EPOCH_LOCKED . +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. 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 routines must be used and the caller can no longer modify a list entry