/* futex operations for glibc-internal use.  Stub version; do not include

   this file directly.

   Copyright (C) 2014-2018 Free Software Foundation, Inc.

   This file is part of the GNU C Library.

   The GNU C Library is free software; you can redistribute it and/or

   modify it under the terms of the GNU Lesser General Public

   License as published by the Free Software Foundation; either

   version 2.1 of the License, or (at your option) any later version.

   The GNU C Library is distributed in the hope that it will be useful,

   but WITHOUT ANY WARRANTY; without even the implied warranty of

   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU

   Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public

   License along with the GNU C Library; if not, see

   <http://www.gnu.org/licenses/>.  */

#ifndef STUB_FUTEX_INTERNAL_H

#define STUB_FUTEX_INTERNAL_H

#include <sys/time.h>

#include <stdio.h>

#include <stdbool.h>

#include <libc-diag.h>

/* This file defines futex operations used internally in glibc.  A futex

   consists of the so-called futex word in userspace, which is of type

   unsigned int and represents an application-specific condition, and kernel

   state associated with this particular futex word (e.g., wait queues).  The

   futex operations we provide are wrappers for the futex syscalls and add

   glibc-specific error checking of the syscall return value.  We abort on

   error codes that are caused by bugs in glibc or in the calling application,

   or when an error code is not known.  We return error codes that can arise

   in correct executions to the caller.  Each operation calls out exactly the

   return values that callers need to handle.

   The private flag must be either FUTEX_PRIVATE or FUTEX_SHARED.

   FUTEX_PRIVATE is always supported, and the implementation can internally

   use FUTEX_SHARED when FUTEX_PRIVATE is requested.  FUTEX_SHARED is not

   necessarily supported (use futex_supports_pshared to detect this).

   We expect callers to only use these operations if futexes and the

   specific futex operations being used are supported (e.g., FUTEX_SHARED).

   Given that waking other threads waiting on a futex involves concurrent

   accesses to the futex word, you must use atomic operations to access the

   futex word.

   Both absolute and relative timeouts can be used.  An absolute timeout

   expires when the given specific point in time on the CLOCK_REALTIME clock

   passes, or when it already has passed.  A relative timeout expires when

   the given duration of time on the CLOCK_MONOTONIC clock passes.  Relative

   timeouts may be imprecise (see futex_supports_exact_relative_timeouts).

   Due to POSIX requirements on when synchronization data structures such

   as mutexes or semaphores can be destroyed and due to the futex design

   having separate fast/slow paths for wake-ups, we need to consider that

   futex_wake calls might effectively target a data structure that has been

   destroyed and reused for another object, or unmapped; thus, some

   errors or spurious wake-ups can happen in correct executions that would

   not be possible in a program using just a single futex whose lifetime

   does not end before the program terminates.  For background, see:

   https://sourceware.org/ml/libc-alpha/2014-04/msg00075.html

   https://lkml.org/lkml/2014/11/27/472  */

/* Defined this way for interoperability with lowlevellock.

   FUTEX_PRIVATE must be zero because the initializers for pthread_mutex_t,

   pthread_rwlock_t, and pthread_cond_t initialize the respective field of

   those structures to zero, and we want FUTEX_PRIVATE to be the default.  */

#define FUTEX_PRIVATE LLL_PRIVATE

#define FUTEX_SHARED  LLL_SHARED

#if FUTEX_PRIVATE != 0

# error FUTEX_PRIVATE must be equal to 0

#endif

/* Returns EINVAL if PSHARED is neither PTHREAD_PROCESS_PRIVATE nor

   PTHREAD_PROCESS_SHARED; otherwise, returns 0 if PSHARED is supported, and

   ENOTSUP if not.  */

static __always_inline int

futex_supports_pshared (int pshared);

/* Returns true if relative timeouts are robust to concurrent changes to the

   system clock.  If this returns false, relative timeouts can still be used

   but might be effectively longer or shorter than requested.  */

static __always_inline bool

futex_supports_exact_relative_timeouts (void);

/* Atomically wrt other futex operations on the same futex, this blocks iff

   the value *FUTEX_WORD matches the expected value.  This is

   semantically equivalent to:

     l = <get lock associated with futex> (FUTEX_WORD);

     wait_flag = <get wait_flag associated with futex> (FUTEX_WORD);

     lock (l);

     val = atomic_load_relaxed (FUTEX_WORD);

     if (val != expected) { unlock (l); return EAGAIN; }

     atomic_store_relaxed (wait_flag, true);

     unlock (l);

     // Now block; can time out in futex_time_wait (see below)

     while (atomic_load_relaxed(wait_flag) && !<spurious wake-up>);

   Note that no guarantee of a happens-before relation between a woken

   futex_wait and a futex_wake is documented; however, this does not matter

   in practice because we have to consider spurious wake-ups (see below),

   and thus would not be able to reliably reason about which futex_wake woke

   us.

   Returns 0 if woken by a futex operation or spuriously.  (Note that due to

   the POSIX requirements mentioned above, we need to conservatively assume

   that unrelated futex_wake operations could wake this futex; it is easiest

   to just be prepared for spurious wake-ups.)

   Returns EAGAIN if the futex word did not match the expected value.

   Returns EINTR if waiting was interrupted by a signal.

   Note that some previous code in glibc assumed the underlying futex

   operation (e.g., syscall) to start with or include the equivalent of a

   seq_cst fence; this allows one to avoid an explicit seq_cst fence before

   a futex_wait call when synchronizing similar to Dekker synchronization.

   However, we make no such guarantee here.  */

static __always_inline int

futex_wait (unsigned int *futex_word, unsigned int expected, int private);

/* Like futex_wait but does not provide any indication why we stopped waiting.

   Thus, when this function returns, you have to always check FUTEX_WORD to

   determine whether you need to continue waiting, and you cannot detect

   whether the waiting was interrupted by a signal.  Example use:

     while (atomic_load_relaxed (&futex_word) == 23)

       futex_wait_simple (&futex_word, 23, FUTEX_PRIVATE);

   This is common enough to make providing this wrapper worthwhile.  */

static __always_inline void

futex_wait_simple (unsigned int *futex_word, unsigned int expected,

		   int private)

{

  ignore_value (futex_wait (futex_word, expected, private));

}

/* Like futex_wait but is a POSIX cancellation point.  */

static __always_inline int

futex_wait_cancelable (unsigned int *futex_word, unsigned int expected,

		       int private);

/* Like futex_wait, but will eventually time out (i.e., stop being

   blocked) after the duration of time provided (i.e., RELTIME) has

   passed.  The caller must provide a normalized RELTIME.  RELTIME can also

   equal NULL, in which case this function behaves equivalent to futex_wait.

   Returns the same values as futex_wait under those same conditions;

   additionally, returns ETIMEDOUT if the timeout expired.

   */

static __always_inline int

futex_reltimed_wait (unsigned int* futex_word, unsigned int expected,

		     const struct timespec* reltime, int private);

/* Like futex_reltimed_wait but is a POSIX cancellation point.  */

static __always_inline int

futex_reltimed_wait_cancelable (unsigned int* futex_word,

				unsigned int expected,

			        const struct timespec* reltime, int private);

/* Like futex_reltimed_wait, but the provided timeout (ABSTIME) is an

   absolute point in time; a call will time out after this point in time.  */

static __always_inline int

futex_abstimed_wait (unsigned int* futex_word, unsigned int expected,

		     const struct timespec* abstime, int private);

/* Like futex_reltimed_wait but is a POSIX cancellation point.  */

static __always_inline int

futex_abstimed_wait_cancelable (unsigned int* futex_word,

				unsigned int expected,

			        const struct timespec* abstime, int private);

/* Atomically wrt other futex operations on the same futex, this unblocks the

   specified number of processes, or all processes blocked on this futex if

   there are fewer than the specified number.  Semantically, this is

   equivalent to:

     l = <get lock associated with futex> (FUTEX_WORD);

     lock (l);

     for (res = 0; PROCESSES_TO_WAKE > 0; PROCESSES_TO_WAKE--, res++) {

       if (<no process blocked on futex>) break;

       wf = <get wait_flag of a process blocked on futex> (FUTEX_WORD);

       // No happens-before guarantee with woken futex_wait (see above)

       atomic_store_relaxed (wf, 0);

     }

     return res;

   Note that we need to support futex_wake calls to past futexes whose memory

   has potentially been reused due to POSIX' requirements on synchronization

   object destruction (see above); therefore, we must not report or abort

   on most errors.  */

static __always_inline void

futex_wake (unsigned int* futex_word, int processes_to_wake, int private);

/* Calls __libc_fatal with an error message.  Convenience function for

   concrete implementations of the futex interface.  */

static __always_inline __attribute__ ((__noreturn__)) void

futex_fatal_error (void)

{

  __libc_fatal ("The futex facility returned an unexpected error code.\n");

}

#endif  /* futex-internal.h */