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 9.\" the first lines of this file unmodified other than the possible 10.\" addition of one or more copyright notices. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice(s), this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 16.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 17.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 18.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY 19.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 20.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 21.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 22.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 25.\" DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd May 13, 2018 30.Dt EPOCH 9 31.Os 32.Sh NAME 33.Nm epoch , 34.Nm epoch_context , 35.Nm epoch_alloc , 36.Nm epoch_free , 37.Nm epoch_enter , 38.Nm epoch_exit , 39.Nm epoch_wait , 40.Nm epoch_call , 41.Nm in_epoch , 42.Nd kernel epoch based reclaimation 43.Sh SYNOPSIS 44.In sys/param.h 45.In sys/proc.h 46.In sys/epoch.h 47.Ft epoch_t 48.Fn epoch_alloc "void" 49.Ft void 50.Fn epoch_enter "epoch_t epoch" 51.Ft void 52.Fn epoch_exit "epoch_t epoch" 53.Ft void 54.Fn epoch_wait "epoch_t epoch" 55.Ft void 56.Fn epoch_call "epoch_t epoch" "epoch_context_t ctx" "void (*callback) (epoch_context_t)" 57.Ft int 58.Fn in_epoch "void" 59.Sh DESCRIPTION 60Epochs are used to guarantee liveness and immutability of data by 61deferring reclamation and mutation until a grace period has elapsed. 62Epochs do not have any lock ordering issues. Entering and leaving 63an epoch section will never block. 64.Pp 65Epochs are allocated with 66.Fn epoch_alloc 67and freed with 68.Fn epoch_free . 69Threads indicate the start of an epoch critical section by calling 70.Fn epoch_enter . 71The end of a critical section is indicated by calling 72.Fn epoch_exit . 73A thread can wait until a grace period has elapsed 74since any threads have entered 75the epoch by calling 76.Fn epoch_wait . 77If the thread can't sleep or is otherwise in a performance sensitive 78path it can ensure that a grace period has elapsed by calling 79.Fn epoch_call 80with a callback with any work that needs to wait for an epoch to elapse. 81Only non-sleepable locks can be acquired during a section protected by 82.Fn epoch_enter 83and 84.Fn epoch_exit . 85INVARIANTS can assert that a thread is in an epoch by using 86.Fn in_epoch . 87.Pp 88The epoch API currently does not support sleeping in epoch sections. 89A caller cannot do epoch_enter recursively on different epochs. A 90caller should never call 91.Fn epoch_wait 92in the middle of an epoch section as this will lead to a deadlock. 93.Pp 94Note that epochs are not a straight replacement for read locks. Callers 95must use safe list and tailq traversal routines in an epoch (see ck_queue). 96When modifying a list referenced from an epoch section safe removal 97routines must be used and the caller can no longer modify a list entry 98in place. An item to be modified must be handled with copy on write 99and frees must be deferred until after a grace period has elapsed. 100 101.Sh RETURN VALUES 102.Fn in_epoch 103will return 1 if curthread is in an epoch, 0 otherwise. 104.Sh EXAMPLES 105Async free example: 106 107Thread 1: 108.Bd -literal 109{ 110 epoch_enter(net_epoch); 111 CK_STAILQ_FOREACH(ifa, &ifp->if_addrhead, ifa_link) { 112 sa = ifa->ifa_addr; 113 if (sa->sa_family != AF_INET) 114 continue; 115 sin = (struct sockaddr_in *)sa; 116 if (prison_check_ip4(cred, &sin->sin_addr) == 0) { 117 ia = (struct in_ifaddr *)ifa; 118 break; 119 } 120 } 121 epoch_exit(net_epoch); 122} 123.Ed 124Thread 2: 125.Bd -literal 126void 127ifa_free(struct ifaddr *ifa) 128{ 129 130 if (refcount_release(&ifa->ifa_refcnt)) 131 epoch_call(net_epoch, &ifa->ifa_epoch_ctx, ifa_destroy); 132} 133 134{ 135 136 IF_ADDR_WLOCK(ifp); 137 CK_STAILQ_REMOVE(&ifp->if_addrhead, ifa, ifaddr, ifa_link); 138 /* mark as unlinked */ 139 ifa->ifa_addr->sa_family = AF_UNSPEC; 140 IF_ADDR_WUNLOCK(ifp); 141 ifa_free(ifa); 142} 143.Ed 144.Pp 145Thread 1 traverses the ifaddr list in an epoch. Thread 2 unlinks 146with the corresponding epoch safe macro, marks as logically free, 147and then defers deletion. More general mutation or a synchronous 148free would have to follow a a call to 149.Fn epoch_wait . 150.Sh ERRORS 151None. 152.El 153.Sh SEE ALSO 154.Xr locking 9 , 155.Xr mtx_pool 9 , 156.Xr mutex 9 , 157.Xr rwlock 9 , 158.Xr sema 9 , 159.Xr sleep 9 , 160.Xr sx 9 , 161.Xr timeout 9 162