| 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 |
} |