Debian Codegraph @

src/shared/barrier.c

raw
1 /* SPDX-License-Identifier: LGPL-2.1-or-later */
2
3 #include <fcntl.h>
4 #include <poll.h>
5 #include <sys/eventfd.h>
6 #include <unistd.h>
7
8 #include "barrier.h"
9 #include "errno-util.h"
10 #include "fd-util.h"
11 #include "io-util.h"
12
13 /**
14 * Barriers
15 * This barrier implementation provides a simple synchronization method based
16 * on file-descriptors that can safely be used between threads and processes. A
17 * barrier object contains 2 shared counters based on eventfd. Both processes
18 * can now place barriers and wait for the other end to reach a random or
19 * specific barrier.
20 * Barriers are numbered, so you can either wait for the other end to reach any
21 * barrier or the last barrier that you placed. This way, you can use barriers
22 * for one-way *and* full synchronization. Note that even-though barriers are
23 * numbered, these numbers are internal and recycled once both sides reached the
24 * same barrier (implemented as a simple signed counter). It is thus not
25 * possible to address barriers by their ID.
26 *
27 * Barrier-API: Both ends can place as many barriers via barrier_place() as
28 * they want and each pair of barriers on both sides will be implicitly linked.
29 * Each side can use the barrier_wait/sync_*() family of calls to wait for the
30 * other side to place a specific barrier. barrier_wait_next() waits until the
31 * other side calls barrier_place(). No links between the barriers are
32 * considered and this simply serves as most basic asynchronous barrier.
33 * barrier_sync_next() is like barrier_wait_next() and waits for the other side
34 * to place their next barrier via barrier_place(). However, it only waits for
35 * barriers that are linked to a barrier we already placed. If the other side
36 * already placed more barriers than we did, barrier_sync_next() returns
37 * immediately.
38 * barrier_sync() extends barrier_sync_next() and waits until the other end
39 * placed as many barriers via barrier_place() as we did. If they already placed
40 * as many as we did (or more), it returns immediately.
41 *
42 * Additionally to basic barriers, an abortion event is available.
43 * barrier_abort() places an abortion event that cannot be undone. An abortion
44 * immediately cancels all placed barriers and replaces them. Any running and
45 * following wait/sync call besides barrier_wait_abortion() will immediately
46 * return false on both sides (otherwise, they always return true).
47 * barrier_abort() can be called multiple times on both ends and will be a
48 * no-op if already called on this side.
49 * barrier_wait_abortion() can be used to wait for the other side to call
50 * barrier_abort() and is the only wait/sync call that does not return
51 * immediately if we aborted outself. It only returns once the other side
52 * called barrier_abort().
53 *
54 * Barriers can be used for in-process and inter-process synchronization.
55 * However, for in-process synchronization you could just use mutexes.
56 * Therefore, main target is IPC and we require both sides to *not* share the FD
57 * table. If that's given, barriers provide target tracking: If the remote side
58 * exit()s, an abortion event is implicitly queued on the other side. This way,
59 * a sync/wait call will be woken up if the remote side crashed or exited
60 * unexpectedly. However, note that these abortion events are only queued if the
61 * barrier-queue has been drained. Therefore, it is safe to place a barrier and
62 * exit. The other side can safely wait on the barrier even though the exit
63 * queued an abortion event. Usually, the abortion event would overwrite the
64 * barrier, however, that's not true for exit-abortion events. Those are only
65 * queued if the barrier-queue is drained (thus, the receiving side has placed
66 * more barriers than the remote side).
67 */
68
69 /**
70 * barrier_create() - Initialize a barrier object
71 * @obj: barrier to initialize
72 *
73 * This initializes a barrier object. The caller is responsible of allocating
74 * the memory and keeping it valid. The memory does not have to be zeroed
75 * beforehand.
76 * Two eventfd objects are allocated for each barrier. If allocation fails, an
77 * error is returned.
78 *
79 * If this function fails, the barrier is reset to an invalid state so it is
80 * safe to call barrier_destroy() on the object regardless whether the
81 * initialization succeeded or not.
82 *
83 * The caller is responsible to destroy the object via barrier_destroy() before
84 * releasing the underlying memory.
85 *
86 * Returns: 0 on success, negative error code on failure.
87 */
88 int barrier_create(Barrier *b) {
89 _unused_ _cleanup_(barrier_destroyp) Barrier *staging = b;
90
91 assert(b);
92
93 b->me = eventfd(0, EFD_CLOEXEC | EFD_NONBLOCK);
94 if (b->me < 0)
95 return -errno;
96
97 b->them = eventfd(0, EFD_CLOEXEC | EFD_NONBLOCK);
98 if (b->them < 0)
99 return -errno;
100
101 if (pipe2(b->pipe, O_CLOEXEC | O_NONBLOCK) < 0)
102 return -errno;
103
104 staging = NULL;
105 return 0;
106 }
107
108 /**
109 * barrier_destroy() - Destroy a barrier object
110 * @b: barrier to destroy or NULL
111 *
112 * This destroys a barrier object that has previously been passed to
113 * barrier_create(). The object is released and reset to invalid
114 * state. Therefore, it is safe to call barrier_destroy() multiple
115 * times or even if barrier_create() failed. However, barrier must be
116 * always initialized with BARRIER_NULL.
117 *
118 * If @b is NULL, this is a no-op.
119 */
120 Barrier* barrier_destroy(Barrier *b) {
121 if (!b)
122 return NULL;
123
124 b->me = safe_close(b->me);
125 b->them = safe_close(b->them);
126 safe_close_pair(b->pipe);
127 b->barriers = 0;
128 return NULL;
129 }
130
131 /**
132 * barrier_set_role() - Set the local role of the barrier
133 * @b: barrier to operate on
134 * @role: role to set on the barrier
135 *
136 * This sets the roles on a barrier object. This is needed to know
137 * which side of the barrier you're on. Usually, the parent creates
138 * the barrier via barrier_create() and then calls fork() or clone().
139 * Therefore, the FDs are duplicated and the child retains the same
140 * barrier object.
141 *
142 * Both sides need to call barrier_set_role() after fork() or clone()
143 * are done. If this is not done, barriers will not work correctly.
144 *
145 * Note that barriers could be supported without fork() or clone(). However,
146 * this is currently not needed so it hasn't been implemented.
147 */
148 void barrier_set_role(Barrier *b, unsigned role) {
149 assert(b);
150 assert(IN_SET(role, BARRIER_PARENT, BARRIER_CHILD));
151 /* make sure this is only called once */
152 assert(b->pipe[0] >= 0 && b->pipe[1] >= 0);
153
154 if (role == BARRIER_PARENT)
155 b->pipe[1] = safe_close(b->pipe[1]);
156 else {
157 b->pipe[0] = safe_close(b->pipe[0]);
158
159 /* swap me/them for children */
160 SWAP_TWO(b->me, b->them);
161 }
162 }
163
164 /* places barrier; returns false if we aborted, otherwise true */
165 static bool barrier_write(Barrier *b, uint64_t buf) {
166 ssize_t len;
167
168 /* prevent new sync-points if we already aborted */
169 if (barrier_i_aborted(b))
170 return false;
171
172 assert(b->me >= 0);
173 do
174 len = write(b->me, &buf, sizeof(buf));
175 while (len < 0 && ERRNO_IS_TRANSIENT(errno));
176
177 if (len != sizeof(buf))
178 goto error;
179
180 /* lock if we aborted */
181 if (buf >= (uint64_t)BARRIER_ABORTION) {
182 if (barrier_they_aborted(b))
183 b->barriers = BARRIER_WE_ABORTED;
184 else
185 b->barriers = BARRIER_I_ABORTED;
186 } else if (!barrier_is_aborted(b))
187 b->barriers += buf;
188
189 return !barrier_i_aborted(b);
190
191 error:
192 /* If there is an unexpected error, we have to make this fatal. There
193 * is no way we can recover from sync-errors. Therefore, we close the
194 * pipe-ends and treat this as abortion. The other end will notice the
195 * pipe-close and treat it as abortion, too. */
196
197 safe_close_pair(b->pipe);
198 b->barriers = BARRIER_WE_ABORTED;
199 return false;
200 }
201
202 /* waits for barriers; returns false if they aborted, otherwise true */
203 static bool barrier_read(Barrier *b, int64_t comp) {
204 if (barrier_they_aborted(b))
205 return false;
206
207 while (b->barriers > comp) {
208 struct pollfd pfd[2] = {
209 { .fd = b->pipe[0] >= 0 ? b->pipe[0] : b->pipe[1],
210 .events = POLLHUP },
211 { .fd = b->them,
212 .events = POLLIN }};
213 uint64_t buf;
214 int r;
215
216 r = ppoll_usec(pfd, ELEMENTSOF(pfd), USEC_INFINITY);
217 if (r == -EINTR)
218 continue;
219 if (r < 0)
220 goto error;
221
222 if (pfd[1].revents) {
223 ssize_t len;
224
225 /* events on @them signal new data for us */
226 len = read(b->them, &buf, sizeof(buf));
227 if (len < 0 && ERRNO_IS_TRANSIENT(errno))
228 continue;
229
230 if (len != sizeof(buf))
231 goto error;
232 } else if (pfd[0].revents & (POLLHUP | POLLERR | POLLNVAL))
233 /* POLLHUP on the pipe tells us the other side exited.
234 * We treat this as implicit abortion. But we only
235 * handle it if there's no event on the eventfd. This
236 * guarantees that exit-abortions do not overwrite real
237 * barriers. */
238 buf = BARRIER_ABORTION;
239 else
240 continue;
241
242 /* lock if they aborted */
243 if (buf >= (uint64_t)BARRIER_ABORTION) {
244 if (barrier_i_aborted(b))
245 b->barriers = BARRIER_WE_ABORTED;
246 else
247 b->barriers = BARRIER_THEY_ABORTED;
248 } else if (!barrier_is_aborted(b))
249 b->barriers -= buf;
250 }
251
252 return !barrier_they_aborted(b);
253
254 error:
255 /* If there is an unexpected error, we have to make this fatal. There
256 * is no way we can recover from sync-errors. Therefore, we close the
257 * pipe-ends and treat this as abortion. The other end will notice the
258 * pipe-close and treat it as abortion, too. */
259
260 safe_close_pair(b->pipe);
261 b->barriers = BARRIER_WE_ABORTED;
262 return false;
263 }
264
265 /**
266 * barrier_place() - Place a new barrier
267 * @b: barrier object
268 *
269 * This places a new barrier on the barrier object. If either side already
270 * aborted, this is a no-op and returns "false". Otherwise, the barrier is
271 * placed and this returns "true".
272 *
273 * Returns: true if barrier was placed, false if either side aborted.
274 */
275 bool barrier_place(Barrier *b) {
276 assert(b);
277
278 if (barrier_is_aborted(b))
279 return false;
280
281 barrier_write(b, BARRIER_SINGLE);
282 return true;
283 }
284
285 /**
286 * barrier_abort() - Abort the synchronization
287 * @b: barrier object to abort
288 *
289 * This aborts the barrier-synchronization. If barrier_abort() was already
290 * called on this side, this is a no-op. Otherwise, the barrier is put into the
291 * ABORT-state and will stay there. The other side is notified about the
292 * abortion. Any following attempt to place normal barriers or to wait on normal
293 * barriers will return immediately as "false".
294 *
295 * You can wait for the other side to call barrier_abort(), too. Use
296 * barrier_wait_abortion() for that.
297 *
298 * Returns: false if the other side already aborted, true otherwise.
299 */
300 bool barrier_abort(Barrier *b) {
301 assert(b);
302
303 barrier_write(b, BARRIER_ABORTION);
304 return !barrier_they_aborted(b);
305 }
306
307 /**
308 * barrier_wait_next() - Wait for the next barrier of the other side
309 * @b: barrier to operate on
310 *
311 * This waits until the other side places its next barrier. This is independent
312 * of any barrier-links and just waits for any next barrier of the other side.
313 *
314 * If either side aborted, this returns false.
315 *
316 * Returns: false if either side aborted, true otherwise.
317 */
318 bool barrier_wait_next(Barrier *b) {
319 assert(b);
320
321 if (barrier_is_aborted(b))
322 return false;
323
324 barrier_read(b, b->barriers - 1);
325 return !barrier_is_aborted(b);
326 }
327
328 /**
329 * barrier_wait_abortion() - Wait for the other side to abort
330 * @b: barrier to operate on
331 *
332 * This waits until the other side called barrier_abort(). This can be called
333 * regardless whether the local side already called barrier_abort() or not.
334 *
335 * If the other side has already aborted, this returns immediately.
336 *
337 * Returns: false if the local side aborted, true otherwise.
338 */
339 bool barrier_wait_abortion(Barrier *b) {
340 assert(b);
341
342 barrier_read(b, BARRIER_THEY_ABORTED);
343 return !barrier_i_aborted(b);
344 }
345
346 /**
347 * barrier_sync_next() - Wait for the other side to place a next linked barrier
348 * @b: barrier to operate on
349 *
350 * This is like barrier_wait_next() and waits for the other side to call
351 * barrier_place(). However, this only waits for linked barriers. That means, if
352 * the other side already placed more barriers than (or as much as) we did, this
353 * returns immediately instead of waiting.
354 *
355 * If either side aborted, this returns false.
356 *
357 * Returns: false if either side aborted, true otherwise.
358 */
359 bool barrier_sync_next(Barrier *b) {
360 assert(b);
361
362 if (barrier_is_aborted(b))
363 return false;
364
365 barrier_read(b, MAX((int64_t)0, b->barriers - 1));
366 return !barrier_is_aborted(b);
367 }
368
369 /**
370 * barrier_sync() - Wait for the other side to place as many barriers as we did
371 * @b: barrier to operate on
372 *
373 * This is like barrier_sync_next() but waits for the other side to call
374 * barrier_place() as often as we did (in total). If they already placed as much
375 * as we did (or more), this returns immediately instead of waiting.
376 *
377 * If either side aborted, this returns false.
378 *
379 * Returns: false if either side aborted, true otherwise.
380 */
381 bool barrier_sync(Barrier *b) {
382 assert(b);
383
384 if (barrier_is_aborted(b))
385 return false;
386
387 barrier_read(b, 0);
388 return !barrier_is_aborted(b);
389 }