2 .\" Copyright (C) 2018 Matthew Macy <mmacy@FreeBSD.org>.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
42 .Nd kernel epoch based reclaimation
48 .Fn epoch_alloc "int flags"
50 .Fn epoch_enter "epoch_t epoch"
52 .Fn epoch_enter_preempt "epoch_t epoch"
54 .Fn epoch_exit "epoch_t epoch"
56 .Fn epoch_exit_preempt "epoch_t epoch"
58 .Fn epoch_wait "epoch_t epoch"
60 .Fn epoch_wait_preempt "epoch_t epoch"
62 .Fn epoch_call "epoch_t epoch" "epoch_context_t ctx" "void (*callback) (epoch_context_t)"
66 Epochs are used to guarantee liveness and immutability of data by
67 deferring reclamation and mutation until a grace period has elapsed.
68 Epochs do not have any lock ordering issues. Entering and leaving
69 an epoch section will never block.
71 Epochs are allocated with
75 The flags passed to epoch_alloc determine whether preemption is
76 allowed during a section or not (the dafult), as specified by
78 Threads indicate the start of an epoch critical section by calling
80 The end of a critical section is indicated by calling
82 The _preempt variants can be used around code which requires preemption.
83 A thread can wait until a grace period has elapsed
84 since any threads have entered
88 .Fn epoch_wait_preempt ,
89 depending on the epoch_type.
90 The use of a default epoch type allows one to use
92 which is guaranteed to have much shorter completion times since
93 we know that none of the threads in an epoch section will be preempted
94 before completing its section.
95 If the thread can't sleep or is otherwise in a performance sensitive
96 path it can ensure that a grace period has elapsed by calling
98 with a callback with any work that needs to wait for an epoch to elapse.
99 Only non-sleepable locks can be acquired during a section protected by
100 .Fn epoch_enter_preempt
102 .Fn epoch_exit_preempt .
103 INVARIANTS can assert that a thread is in an epoch by using
106 The epoch API currently does not support sleeping in epoch_preempt sections.
107 A caller cannot do epoch_enter recursively on different preemptible epochs. A
108 caller should never call
110 in the middle of an epoch section as this will lead to a deadlock.
112 Note that epochs are not a straight replacement for read locks. Callers
113 must use safe list and tailq traversal routines in an epoch (see ck_queue).
114 When modifying a list referenced from an epoch section safe removal
115 routines must be used and the caller can no longer modify a list entry
116 in place. An item to be modified must be handled with copy on write
117 and frees must be deferred until after a grace period has elapsed.
120 will return 1 if curthread is in an epoch, 0 otherwise.
122 One must be cautious when using
123 .Fn epoch_wait_preempt
124 threads are pinned during epoch sections so if a thread in a section is then
125 preempted by a higher priority compute bound thread on that CPU it can be
126 prevented from leaving the section. Thus the wait time for the waiter is
127 potentially unbounded.
134 in_pcbladdr(struct inpcb *inp, struct in_addr *faddr, struct in_laddr *laddr,
138 epoch_enter(net_epoch);
139 CK_STAILQ_FOREACH(ifa, &ifp->if_addrhead, ifa_link) {
141 if (sa->sa_family != AF_INET)
143 sin = (struct sockaddr_in *)sa;
144 if (prison_check_ip4(cred, &sin->sin_addr) == 0) {
145 ia = (struct in_ifaddr *)ifa;
149 epoch_exit(net_epoch);
156 ifa_free(struct ifaddr *ifa)
159 if (refcount_release(&ifa->ifa_refcnt))
160 epoch_call(net_epoch, &ifa->ifa_epoch_ctx, ifa_destroy);
164 if_purgeaddrs(struct ifnet *ifp)
169 CK_STAILQ_REMOVE(&ifp->if_addrhead, ifa, ifaddr, ifa_link);
170 IF_ADDR_WUNLOCK(ifp);
175 Thread 1 traverses the ifaddr list in an epoch. Thread 2 unlinks
176 with the corresponding epoch safe macro, marks as logically free,
177 and then defers deletion. More general mutation or a synchronous
178 free would have to follow a a call to