src/shared/barrier.c

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