From owner-svn-src-all@freebsd.org Sun May 13 23:16:05 2018 Return-Path: Delivered-To: svn-src-all@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 6DBC0FD96D4; Sun, 13 May 2018 23:16:05 +0000 (UTC) (envelope-from mmacy@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 2047B84C20; Sun, 13 May 2018 23:16:05 +0000 (UTC) (envelope-from mmacy@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 F140C140C9; Sun, 13 May 2018 23:16:04 +0000 (UTC) (envelope-from mmacy@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id w4DNG4eo092483; Sun, 13 May 2018 23:16:04 GMT (envelope-from mmacy@FreeBSD.org) Received: (from mmacy@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id w4DNG4oh092482; Sun, 13 May 2018 23:16:04 GMT (envelope-from mmacy@FreeBSD.org) Message-Id: <201805132316.w4DNG4oh092482@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: mmacy set sender to mmacy@FreeBSD.org using -f From: Matt Macy Date: Sun, 13 May 2018 23:16:04 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r333590 - head/share/man/man9 X-SVN-Group: head X-SVN-Commit-Author: mmacy X-SVN-Commit-Paths: head/share/man/man9 X-SVN-Commit-Revision: 333590 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.25 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 13 May 2018 23:16:05 -0000 Author: mmacy Date: Sun May 13 23:16:04 2018 New Revision: 333590 URL: https://svnweb.freebsd.org/changeset/base/333590 Log: Add epoch(9) man page Reviewed by: gallatin@ Approved by: sbruno@ Added: head/share/man/man9/epoch.9 (contents, props changed) Modified: head/share/man/man9/Makefile Modified: head/share/man/man9/Makefile ============================================================================== --- head/share/man/man9/Makefile Sun May 13 23:04:35 2018 (r333589) +++ head/share/man/man9/Makefile Sun May 13 23:16:04 2018 (r333590) @@ -123,6 +123,7 @@ MAN= accept_filter.9 \ drbr.9 \ driver.9 \ DRIVER_MODULE.9 \ + epoch.9 \ EVENTHANDLER.9 \ eventtimers.9 \ extattr.9 \ Added: head/share/man/man9/epoch.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/epoch.9 Sun May 13 23:16:04 2018 (r333590) @@ -0,0 +1,161 @@ +.\" +.\" Copyright (C) 2018 Matthew Macy . +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +.\" DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 13, 2018 +.Dt EPOCH 9 +.Os +.Sh NAME +.Nm epoch , +.Nm epoch_context , +.Nm epoch_alloc , +.Nm epoch_free , +.Nm epoch_enter , +.Nm epoch_exit , +.Nm epoch_wait , +.Nm epoch_call , +.Nm in_epoch , +.Nd kernel epoch based reclaimation +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.In sys/epoch.h +.Ft epoch_t +.Fn epoch_alloc "void" +.Ft void +.Fn epoch_enter "epoch_t epoch" +.Ft void +.Fn epoch_exit "epoch_t epoch" +.Ft void +.Fn epoch_wait "epoch_t epoch" +.Ft void +.Fn epoch_call "epoch_t epoch" "epoch_context_t ctx" "void (*callback) (epoch_context_t)" +.Ft int +.Fn in_epoch "void" +.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. +.Pp +Epochs are allocated with +.Fn epoch_alloc +and freed with +.Fn epoch_free . +Threads indicate the start of an epoch critical section by calling +.Fn epoch_enter . +The end of a critical section is indicated by calling +.Fn epoch_exit . +A thread can wait until a grace period has elapsed +since any threads have entered +the epoch by calling +.Fn epoch_wait . +If the thread can't sleep or is otherwise in a performance sensitive +path it can ensure that a grace period has elapsed by calling +.Fn epoch_call +with a callback with any work that needs to wait for an epoch to elapse. +Only non-sleepable locks can be acquired during a section protected by +.Fn epoch_enter +and +.Fn epoch_exit . +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 sections. +A caller cannot do epoch_enter recursively on different 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). +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 +and frees must be deferred until after a grace period has elapsed. + +.Sh RETURN VALUES +.Fn in_epoch +will return 1 if curthread is in an epoch, 0 otherwise. +.Sh EXAMPLES +Async free example: + +Thread 1: +.Bd -literal +{ + epoch_enter(net_epoch); + CK_STAILQ_FOREACH(ifa, &ifp->if_addrhead, ifa_link) { + sa = ifa->ifa_addr; + if (sa->sa_family != AF_INET) + continue; + sin = (struct sockaddr_in *)sa; + if (prison_check_ip4(cred, &sin->sin_addr) == 0) { + ia = (struct in_ifaddr *)ifa; + break; + } + } + epoch_exit(net_epoch); +} +.Ed +Thread 2: +.Bd -literal +void +ifa_free(struct ifaddr *ifa) +{ + + if (refcount_release(&ifa->ifa_refcnt)) + epoch_call(net_epoch, &ifa->ifa_epoch_ctx, ifa_destroy); +} + +{ + + IF_ADDR_WLOCK(ifp); + CK_STAILQ_REMOVE(&ifp->if_addrhead, ifa, ifaddr, ifa_link); + /* mark as unlinked */ + ifa->ifa_addr->sa_family = AF_UNSPEC; + IF_ADDR_WUNLOCK(ifp); + ifa_free(ifa); +} +.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 +.Fn epoch_wait . +.Sh ERRORS +None. +.El +.Sh SEE ALSO +.Xr locking 9 , +.Xr mtx_pool 9 , +.Xr mutex 9 , +.Xr rwlock 9 , +.Xr sema 9 , +.Xr sleep 9 , +.Xr sx 9 , +.Xr timeout 9