sysdeps/nptl/futex-internal.h

   1 /* futex operations for glibc-internal use.  Stub version; do not include
   2    this file directly.
   3    Copyright (C) 2014-2016 Free Software Foundation, Inc.
   4    This file is part of the GNU C Library.
   5
   6    The GNU C Library is free software; you can redistribute it and/or
   7    modify it under the terms of the GNU Lesser General Public
   8    License as published by the Free Software Foundation; either
   9    version 2.1 of the License, or (at your option) any later version.
  10
  11    The GNU C Library is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Lesser General Public License for more details.
  15
  16    You should have received a copy of the GNU Lesser General Public
  17    License along with the GNU C Library; if not, see
  18    <http://www.gnu.org/licenses/>.  */
  19
  20 #ifndef STUB_FUTEX_INTERNAL_H
  21 #define STUB_FUTEX_INTERNAL_H
  22
  23 #include <sys/time.h>
  24 #include <stdio.h>
  25 #include <stdbool.h>
  26 #include <libc-internal.h>
  27
  28 /* This file defines futex operations used internally in glibc.  A futex
  29    consists of the so-called futex word in userspace, which is of type
  30    unsigned int and represents an application-specific condition, and kernel
  31    state associated with this particular futex word (e.g., wait queues).  The
  32    futex operations we provide are wrappers for the futex syscalls and add
  33    glibc-specific error checking of the syscall return value.  We abort on
  34    error codes that are caused by bugs in glibc or in the calling application,
  35    or when an error code is not known.  We return error codes that can arise
  36    in correct executions to the caller.  Each operation calls out exactly the
  37    return values that callers need to handle.
  38
  39    The private flag must be either FUTEX_PRIVATE or FUTEX_SHARED.
  40    FUTEX_PRIVATE is always supported, and the implementation can internally
  41    use FUTEX_SHARED when FUTEX_PRIVATE is requested.  FUTEX_SHARED is not
  42    necessarily supported (use futex_supports_pshared to detect this).
  43
  44    We expect callers to only use these operations if futexes and the
  45    specific futex operations being used are supported (e.g., FUTEX_SHARED).
  46
  47    Given that waking other threads waiting on a futex involves concurrent
  48    accesses to the futex word, you must use atomic operations to access the
  49    futex word.
  50
  51    Both absolute and relative timeouts can be used.  An absolute timeout
  52    expires when the given specific point in time on the CLOCK_REALTIME clock
  53    passes, or when it already has passed.  A relative timeout expires when
  54    the given duration of time on the CLOCK_MONOTONIC clock passes.  Relative
  55    timeouts may be imprecise (see futex_supports_exact_relative_timeouts).
  56
  57    Due to POSIX requirements on when synchronization data structures such
  58    as mutexes or semaphores can be destroyed and due to the futex design
  59    having separate fast/slow paths for wake-ups, we need to consider that
  60    futex_wake calls might effectively target a data structure that has been
  61    destroyed and reused for another object, or unmapped; thus, some
  62    errors or spurious wake-ups can happen in correct executions that would
  63    not be possible in a program using just a single futex whose lifetime
  64    does not end before the program terminates.  For background, see:
  65    https://sourceware.org/ml/libc-alpha/2014-04/msg00075.html
  66    https://lkml.org/lkml/2014/11/27/472  */
  67
  68 /* Defined this way for interoperability with lowlevellock.
  69    FUTEX_PRIVATE must be zero because the initializers for pthread_mutex_t,
  70    pthread_rwlock_t, and pthread_cond_t initialize the respective field of
  71    those structures to zero, and we want FUTEX_PRIVATE to be the default.  */
  72 #define FUTEX_PRIVATE LLL_PRIVATE
  73 #define FUTEX_SHARED  LLL_SHARED
  74 #if FUTEX_PRIVATE != 0
  75 # error FUTEX_PRIVATE must be equal to 0
  76 #endif
  77
  78 /* Returns EINVAL if PSHARED is neither PTHREAD_PROCESS_PRIVATE nor
  79    PTHREAD_PROCESS_SHARED; otherwise, returns 0 if PSHARED is supported, and
  80    ENOTSUP if not.  */
  81 static __always_inline int
  82 futex_supports_pshared (int pshared);
  83
  84 /* Returns true if relative timeouts are robust to concurrent changes to the
  85    system clock.  If this returns false, relative timeouts can still be used
  86    but might be effectively longer or shorter than requested.  */
  87 static __always_inline bool
  88 futex_supports_exact_relative_timeouts (void);
  89
  90 /* Atomically wrt other futex operations on the same futex, this blocks iff
  91    the value *FUTEX_WORD matches the expected value.  This is
  92    semantically equivalent to:
  93      l = <get lock associated with futex> (FUTEX_WORD);
  94      wait_flag = <get wait_flag associated with futex> (FUTEX_WORD);
  95      lock (l);
  96      val = atomic_load_relaxed (FUTEX_WORD);
  97      if (val != expected) { unlock (l); return EAGAIN; }
  98      atomic_store_relaxed (wait_flag, true);
  99      unlock (l);
 100      // Now block; can time out in futex_time_wait (see below)
 101      while (atomic_load_relaxed(wait_flag) && !<spurious wake-up>);
 102
 103    Note that no guarantee of a happens-before relation between a woken
 104    futex_wait and a futex_wake is documented; however, this does not matter
 105    in practice because we have to consider spurious wake-ups (see below),
 106    and thus would not be able to reliably reason about which futex_wake woke
 107    us.
 108
 109    Returns 0 if woken by a futex operation or spuriously.  (Note that due to
 110    the POSIX requirements mentioned above, we need to conservatively assume
 111    that unrelated futex_wake operations could wake this futex; it is easiest
 112    to just be prepared for spurious wake-ups.)
 113    Returns EAGAIN if the futex word did not match the expected value.
 114    Returns EINTR if waiting was interrupted by a signal.
 115
 116    Note that some previous code in glibc assumed the underlying futex
 117    operation (e.g., syscall) to start with or include the equivalent of a
 118    seq_cst fence; this allows one to avoid an explicit seq_cst fence before
 119    a futex_wait call when synchronizing similar to Dekker synchronization.
 120    However, we make no such guarantee here.  */
 121 static __always_inline int
 122 futex_wait (unsigned int *futex_word, unsigned int expected, int private);
 123
 124 /* Like futex_wait but does not provide any indication why we stopped waiting.
 125    Thus, when this function returns, you have to always check FUTEX_WORD to
 126    determine whether you need to continue waiting, and you cannot detect
 127    whether the waiting was interrupted by a signal.  Example use:
 128      while (atomic_load_relaxed (&futex_word) == 23)
 129        futex_wait_simple (&futex_word, 23, FUTEX_PRIVATE);
 130    This is common enough to make providing this wrapper worthwhile.  */
 131 static __always_inline void
 132 futex_wait_simple (unsigned int *futex_word, unsigned int expected,
 133                    int private)
 134 {
 135   ignore_value (futex_wait (futex_word, expected, private));
 136 }
 137
 138
 139 /* Like futex_wait but is a POSIX cancellation point.  */
 140 static __always_inline int
 141 futex_wait_cancelable (unsigned int *futex_word, unsigned int expected,
 142                        int private);
 143
 144 /* Like futex_wait, but will eventually time out (i.e., stop being
 145    blocked) after the duration of time provided (i.e., RELTIME) has
 146    passed.  The caller must provide a normalized RELTIME.  RELTIME can also
 147    equal NULL, in which case this function behaves equivalent to futex_wait.
 148
 149    Returns the same values as futex_wait under those same conditions;
 150    additionally, returns ETIMEDOUT if the timeout expired.
 151    */
 152 static __always_inline int
 153 futex_reltimed_wait (unsigned int* futex_word, unsigned int expected,
 154                      const struct timespec* reltime, int private);
 155
 156 /* Like futex_reltimed_wait but is a POSIX cancellation point.  */
 157 static __always_inline int
 158 futex_reltimed_wait_cancelable (unsigned int* futex_word,
 159                                 unsigned int expected,
 160                                 const struct timespec* reltime, int private);
 161
 162 /* Like futex_reltimed_wait, but the provided timeout (ABSTIME) is an
 163    absolute point in time; a call will time out after this point in time.  */
 164 static __always_inline int
 165 futex_abstimed_wait (unsigned int* futex_word, unsigned int expected,
 166                      const struct timespec* abstime, int private);
 167
 168 /* Like futex_reltimed_wait but is a POSIX cancellation point.  */
 169 static __always_inline int
 170 futex_abstimed_wait_cancelable (unsigned int* futex_word,
 171                                 unsigned int expected,
 172                                 const struct timespec* abstime, int private);
 173
 174 /* Atomically wrt other futex operations on the same futex, this unblocks the
 175    specified number of processes, or all processes blocked on this futex if
 176    there are fewer than the specified number.  Semantically, this is
 177    equivalent to:
 178      l = <get lock associated with futex> (FUTEX_WORD);
 179      lock (l);
 180      for (res = 0; PROCESSES_TO_WAKE > 0; PROCESSES_TO_WAKE--, res++) {
 181        if (<no process blocked on futex>) break;
 182        wf = <get wait_flag of a process blocked on futex> (FUTEX_WORD);
 183        // No happens-before guarantee with woken futex_wait (see above)
 184        atomic_store_relaxed (wf, 0);
 185      }
 186      return res;
 187
 188    Note that we need to support futex_wake calls to past futexes whose memory
 189    has potentially been reused due to POSIX' requirements on synchronization
 190    object destruction (see above); therefore, we must not report or abort
 191    on most errors.  */
 192 static __always_inline void
 193 futex_wake (unsigned int* futex_word, int processes_to_wake, int private);
 194
 195 /* Calls __libc_fatal with an error message.  Convenience function for
 196    concrete implementations of the futex interface.  */
 197 static __always_inline __attribute__ ((__noreturn__)) void
 198 futex_fatal_error (void)
 199 {
 200   __libc_fatal ("The futex facility returned an unexpected error code.");
 201 }
 202
 203 #endif  /* futex-internal.h */