An implementation of a simple futex (fast userspace mutex). Only wait and wake are implemented. More...

#include <futex.h>

Public Types
enum class	Result { Change , WakeUp }

Static Public Member Functions
static Result	wait (const std::atomic_uint32_t *pFutexValue, uint32_t expected, uint32_t waitMask)
	Suspends the caller on the futex while its value remains expected.

static uint32_t	wake (const std::atomic_uint32_t *pFutexValue, uint32_t wakeCount, uint32_t wakeMask=detail::WaitMaskAny)
	Wakes up to wakeCount waiters whose waitMask matches wakeMask.

Detailed Description

An implementation of a simple futex (fast userspace mutex). Only wait and wake are implemented.

The main advantage of futex is performance. It avoids kernel involvement in uncontended cases. When there’s no contention, futexes allow threads to lock and unlock in userspace without entering the kernel, making operations significantly faster and reducing context-switch overhead. Only when there is contention does a futex use the kernel to put threads to sleep and wake them up, resulting in a hybrid model that is more efficient than mutexes, which always require kernel calls.

TODO: Consider using WaitOnAddress for Windows, futex call for Linux etc. The current solution is platform-agnostic but platform-specific solutions might be more performant.

Member Enumeration Documentation

◆ Result

enum class gaia::mt::Futex::Result

strong

Enumerator
Change	Futex value didn't match the expected one.
WakeUp	Futex woken up as a result of wake()

Member Function Documentation

◆ wait()

static Result gaia::mt::Futex::wait	(	const std::atomic_uint32_t *	pFutexValue,
		uint32_t	expected,
		uint32_t	waitMask
	)

inlinestatic

Suspends the caller on the futex while its value remains expected.

Parameters

pFutexValue	Target futex
expected	Expected futex value
waitMask	Mask of waiters to wait for

◆ wake()

static uint32_t gaia::mt::Futex::wake	(	const std::atomic_uint32_t *	pFutexValue,
		uint32_t	wakeCount,
		uint32_t	wakeMask = `detail::WaitMaskAny`
	)

inlinestatic

Wakes up to wakeCount waiters whose waitMask matches wakeMask.