carb::thread::futex

namespace futex

Futex namespace.

FUTEX stands for Fast Userspace muTEX. Put simply, it’s a way of efficiently blocking threads waiting for a condition to become true. It is a low-level system, and a foundation for many synchronization primitives.

Windows has a similar mechanism through WaitOnAddress. While WaitOnAddress allows the value waited on to be either 1, 2, 4 or 8 bytes, Linux requires the value be 32-bit (4 bytes). For Linux sizes other than 4 bytes, detail::Futex has its own simple futex implementation on top of the system futex implementation.

Linux information: http://man7.org/linux/man-pages/man2/futex.2.html

Windows information: https://docs.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-waitonaddress

Warning

Futex is a very low-level system; generally its use should be avoided. There are plenty of higher level synchronization primitives built on top of Futex that should be used instead, such as carb::cpp20::atomic.

Functions

• carb::thread::futex::wait: Waits on a value until woken.

• carb::thread::futex::wait_for: Waits on a value until woken or timed out.

• carb::thread::futex::wait_until: Waits on a value until woken or timed out.

• carb::thread::futex::wake: Wakes threads that are waiting in one of the futex wait functions.

• carb::thread::futex::wake_all: Wakes all threads that are waiting in one of the futex wait functions.

• carb::thread::futex::wake_one: Wakes one thread that is waiting in one of the futex wait functions.