From owner-svn-src-head@freebsd.org Fri Jun 22 06:04:23 2018 Return-Path: Delivered-To: svn-src-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 8897F100F74F; Fri, 22 Jun 2018 06:04:23 +0000 (UTC) (envelope-from eadler@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 39751800CF; Fri, 22 Jun 2018 06:04:23 +0000 (UTC) (envelope-from eadler@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 0F10C1CC6D; Fri, 22 Jun 2018 06:04:23 +0000 (UTC) (envelope-from eadler@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id w5M64MHC028574; Fri, 22 Jun 2018 06:04:22 GMT (envelope-from eadler@FreeBSD.org) Received: (from eadler@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id w5M64MrA028573; Fri, 22 Jun 2018 06:04:22 GMT (envelope-from eadler@FreeBSD.org) Message-Id: <201806220604.w5M64MrA028573@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: eadler set sender to eadler@FreeBSD.org using -f From: Eitan Adler Date: Fri, 22 Jun 2018 06:04:22 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r335531 - head/share/man/man9 X-SVN-Group: head X-SVN-Commit-Author: eadler X-SVN-Commit-Paths: head/share/man/man9 X-SVN-Commit-Revision: 335531 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.26 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 22 Jun 2018 06:04:23 -0000 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 (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 . +.\" Copyright (C) 2018 Matthew Macy . .\" .\" 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.