Futex is a mechanism used to block (wait) and unblock (wake) threads using a 32bit memory address as hints. Blocking a thread is acknowledged only if the 32bit memory address is equal to a given value. This check helps avoid block/unblock deadlocks which occur if a wake() happens before a wait(). Using Futex, other Thread synchronization primitives can be built which efficiently wait for cross-thread events or signals.

Types

Functions

fn timedWait(ptr: *const Atomic(u32), expect: u32, timeout_ns: u64) error{Timeout}!void

Checks if ptr still contains the value expect and, if so, blocks the caller …

Checks if ptr still contains the value expect and, if so, blocks the caller until either:

  • The value at ptr is no longer equal to expect.
  • The caller is unblocked by a matching wake().
  • The caller is unblocked spuriously (“at random”).
  • The caller blocks for longer than the given timeout. In which case, error.Timeout is returned.

The checking of ptr and expect, along with blocking the caller, is done atomically and totally ordered (sequentially consistent) with respect to other wait()/wake() calls on the same ptr.

fn wait(ptr: *const Atomic(u32), expect: u32) void

Checks if ptr still contains the value expect and, if so, blocks the caller …

Checks if ptr still contains the value expect and, if so, blocks the caller until either:

  • The value at ptr is no longer equal to expect.
  • The caller is unblocked by a matching wake().
  • The caller is unblocked spuriously (“at random”).

The checking of ptr and expect, along with blocking the caller, is done atomically and totally ordered (sequentially consistent) with respect to other wait()/wake() calls on the same ptr.

fn wake(ptr: *const Atomic(u32), max_waiters: u32) void

Unblocks at most max_waiters callers blocked in a wait() call on ptr.