Mutex

Data Structures
struct	Mutex

Macros
#define	mutexInit(m, ...)   _mutexInit(m, opt_flags(__VA_ARGS__))
#define	withMutex(m)   blkWrap (mutexAcquire(m), mutexRelease(m))

Typedefs
typedef struct Mutex	Mutex

Enumerations
enum	MUTEX_Flags { MUTEX_NoSpin = 1 }
	Mutex initialization flags. More...

Functions
bool	mutexTryAcquireTimeout (Mutex *m, int64 timeout)
bool	mutexRelease (Mutex *m)
bool	mutexTryAcquire (Mutex *m)
void	mutexAcquire (Mutex *m)
void	mutexDestroy (Mutex *m)

Detailed Description

Fast, adaptive mutexes for exclusive access to shared resources.

The CX Mutex implementation uses futexes and adaptive spinning for efficiency:

• Uncontended locks complete in user space without kernel calls
• Adaptive spinning for short waits before falling back to kernel futex
• Supports timeouts for bounded waiting

Mutexes are NOT reentrant - attempting to acquire the same mutex twice from the same thread will deadlock.

Basic usage:

Mutex m;
mutexInit(&m);
 
mutexAcquire(&m);
// critical section
mutexRelease(&m);
 
mutexDestroy(&m);

Scoped locking with automatic release:

withMutex(&m) {
    // critical section - mutex released automatically at end of block
}

Macro Definition Documentation

mutexInit

#define mutexInit	(		m,
			...
	)		_mutexInit(m, opt_flags(__VA_ARGS__))

void mutexInit(Mutex *m, [flags])

Initialize a mutex for use.

Must be called before using any other mutex operations.

Parameters

m	Pointer to uninitialized mutex structure
...	(flags) Optional MUTEX_Flags (e.g., MUTEX_NoSpin)

Definition at line 74 of file mutex.h.

withMutex

#define withMutex

(

m

)

blkWrap (mutexAcquire(m), mutexRelease(m))

Execute a block with automatic mutex locking and unlocking

Acquires the mutex before executing the following block, and automatically releases it when the block exits (including early returns, breaks, or exceptions).

Example:

withMutex(&myMutex) {
    // critical section
    if (error)
        break;  // mutex automatically released
}

Parameters

m	Mutex to lock for the duration of the block

Definition at line 139 of file mutex.h.

Typedef Documentation

Mutex

typedef struct Mutex Mutex

Mutex synchronization primitive

Internal structure using futex-based locking with adaptive spinning. Futex values: 0=unlocked, 1=locked (no waiters), 2=locked with contention

Enumeration Type Documentation

MUTEX_Flags

enum MUTEX_Flags

Mutex initialization flags.

Enumerator
MUTEX_NoSpin	Disable adaptive spinning, use kernel futex immediately.

Definition at line 52 of file mutex.h.

Function Documentation

mutexAcquire()

void mutexAcquire ( Mutex *  m )

inline

Acquire a mutex, blocking until it becomes available

Blocks the calling thread until the mutex can be acquired. This is equivalent to mutexTryAcquireTimeout() with timeForever.

Parameters

m	Mutex to acquire

Definition at line 120 of file mutex.h.

References mutexTryAcquireTimeout(), and timeForever.

mutexDestroy()

void mutexDestroy

(

Mutex *

m

)

Destroy a mutex and release its resources

Cleans up the mutex after use. The mutex must not be held when destroyed. After destruction, the mutex must be reinitialized before it can be used again.

Parameters

m	Mutex to destroy

mutexRelease()

bool mutexRelease

(

Mutex *

m

)

Release a previously acquired mutex

Releases the mutex so other threads can acquire it. Must be called from the same thread that acquired the mutex. Undefined behavior if called on a mutex not currently held.

Parameters

m	Mutex to release

Returns

true on success

mutexTryAcquire()

bool mutexTryAcquire ( Mutex *  m )

inline

Attempt to acquire a mutex without blocking

Tries to acquire the mutex immediately, returning false if it is already held by another thread. Does not block or wait.

Parameters

m	Mutex to acquire

Returns

true if the mutex was acquired, false if already held

Definition at line 104 of file mutex.h.

mutexTryAcquireTimeout()

bool mutexTryAcquireTimeout	(	Mutex *	m,
		int64	timeout
	)

Attempt to acquire a mutex with a timeout

Tries to acquire the mutex, waiting up to the specified timeout. Uses adaptive spinning before falling back to kernel waits for efficiency.

Parameters

m	Mutex to acquire
timeout	Maximum time to wait in nanoseconds (use timeForever for infinite)

Returns

true if the mutex was acquired, false if timeout expired

Referenced by mutexAcquire().