Date: Fri, 22 Jun 2018 06:04:22 +0000 (UTC) From: Eitan Adler <eadler@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r335531 - head/share/man/man9 Message-ID: <201806220604.w5M64MrA028573@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: eadler Date: Fri Jun 22 06:04:22 2018 New Revision: 335531 URL: https://svnweb.freebsd.org/changeset/base/335531 Log: epoch.9: fix some style and speeling issues Reported by: Yutaro Hayakawa <yhayakawa3720@gmail.com> (spelling) Differential Revision: https://reviews.freebsd.org/D15961 Modified: head/share/man/man9/epoch.9 Modified: head/share/man/man9/epoch.9 ============================================================================== --- head/share/man/man9/epoch.9 Fri Jun 22 04:54:51 2018 (r335530) +++ head/share/man/man9/epoch.9 Fri Jun 22 06:04:22 2018 (r335531) @@ -1,5 +1,5 @@ .\" -.\" Copyright (C) 2018 Matthew Macy <mmacy@FreeBSD.org>. +.\" Copyright (C) 2018 Matthew Macy <mmacy@FreeBSD.org>. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -65,15 +65,15 @@ .Sh DESCRIPTION Epochs are used to guarantee liveness and immutability of data by deferring reclamation and mutation until a grace period has elapsed. -Epochs do not have any lock ordering issues. Entering and leaving -an epoch section will never block. +Epochs do not have any lock ordering issues. +Entering and leaving an epoch section will never block. .Pp Epochs are allocated with .Fn epoch_alloc and freed with .Fn epoch_free . The flags passed to epoch_alloc determine whether preemption is -allowed during a section or not (the dafult), as specified by +allowed during a section or not (the default), as specified by EPOCH_PREEMPT. Threads indicate the start of an epoch critical section by calling .Fn epoch_enter . @@ -104,16 +104,17 @@ INVARIANTS can assert that a thread is in an epoch by .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 +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. .Pp -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). +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 -in place. An item to be modified must be handled with copy on write +in place. +An item to be modified must be handled with copy on write and frees must be deferred until after a grace period has elapsed. .Sh RETURN VALUES .Fn in_epoch @@ -123,11 +124,11 @@ One must be cautious when using .Fn epoch_wait_preempt 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 -prevented from leaving the section. Thus the wait time for the waiter is +prevented from leaving the section. +Thus the wait time for the waiter is potentially unbounded. .Sh EXAMPLES Async free example: - Thread 1: .Bd -literal int @@ -164,7 +165,7 @@ void if_purgeaddrs(struct ifnet *ifp) { - /* .... */ + /* .... * IF_ADDR_WLOCK(ifp); CK_STAILQ_REMOVE(&ifp->if_addrhead, ifa, ifaddr, ifa_link); IF_ADDR_WUNLOCK(ifp); @@ -172,10 +173,11 @@ if_purgeaddrs(struct ifnet *ifp) } .Ed .Pp -Thread 1 traverses the ifaddr list in an epoch. Thread 2 unlinks -with the corresponding epoch safe macro, marks as logically free, -and then defers deletion. More general mutation or a synchronous -free would have to follow a a call to +Thread 1 traverses the ifaddr list in an epoch. +Thread 2 unlinks with the corresponding epoch safe macro, marks as logically free, +and then defers deletion. +More general mutation or a synchronous +free would have to follow a call to .Fn epoch_wait . .Sh ERRORS None.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201806220604.w5M64MrA028573>