Semaphore

Data Structures
struct	Semaphore
	Counting semaphore synchronization primitive. More...

Macros
#define	semaInit(sema, count, ...)   _semaInit(sema, count, opt_flags(__VA_ARGS__))

Typedefs
typedef struct Semaphore	Semaphore
	Counting semaphore synchronization primitive.

Enumerations
enum	SEMA_Flags { SEMA_NoSpin = 0x00000001 }
	Semaphore initialization flags. More...

Functions
bool	semaDestroy (Semaphore *sema)
bool	semaTryDecTimeout (Semaphore *sema, int64 timeout)
bool	semaTryDec (Semaphore *sema)
bool	semaDec (Semaphore *sema)
bool	semaInc (Semaphore *sema, int32 count)

Detailed Description

A counting semaphore for controlling access to a resource with a limited number of concurrent users, or for producer/consumer hand-off of a count of available items.

A semaphore holds a non-negative count. semaDec() (and its timed/non-blocking variants) waits until the count is greater than zero, then decrements it. semaInc() adds to the count and wakes any waiters that can now proceed.

Basic usage:

Semaphore s;
semaInit(&s, 0);   // start with no available slots
 
// Producer: make one item available
semaInc(&s, 1);
 
// Consumer: wait for an item to become available
semaDec(&s);
 
semaDestroy(&s);

Macro Definition Documentation

semaInit

#define semaInit	(		sema,
			count,
			...
	)		_semaInit(sema, count, opt_flags(__VA_ARGS__))

void semaInit(Semaphore *sema, int32 count, [flags])

Initialize a semaphore for use.

Must be called before using any other semaphore operations.

Parameters

sema	Pointer to uninitialized semaphore structure
count	Initial count. Must not be negative
...	(flags) Optional SEMA_Flags (e.g., SEMA_NoSpin)

Definition at line 61 of file sema.h.

Enumeration Type Documentation

SEMA_Flags

enum SEMA_Flags

Semaphore initialization flags.

Enumerator
SEMA_NoSpin	Disable adaptive spinning, use kernel futex immediately.

Definition at line 41 of file sema.h.

Function Documentation

semaDec()

bool semaDec ( Semaphore *  sema )

inline

Decrement a semaphore, blocking until the count is available

Blocks the calling thread until the count is greater than zero, then decrements it. This is equivalent to semaTryDecTimeout() with timeForever.

Parameters

sema	Semaphore to decrement

Returns

true on success

Definition at line 109 of file sema.h.

References semaTryDecTimeout(), and timeForever.

semaDestroy()

bool semaDestroy

(

Semaphore *

sema

)

Destroy a semaphore and release its resources

Cleans up the semaphore after use. After destruction, the semaphore must be reinitialized before it can be used again.

Parameters

sema	Semaphore to destroy

Returns

true on success

semaInc()

bool semaInc ( Semaphore *  sema, int32  count  )

inline

Increment a semaphore's count

Adds count to the semaphore and wakes up to that many waiting threads.

Parameters

sema	Semaphore to increment
count	Amount to add to the count

Returns

true on success

Definition at line 120 of file sema.h.

semaTryDec()

bool semaTryDec ( Semaphore *  sema )

inline

Attempt to decrement a semaphore without blocking

Decrements the count immediately if it is greater than zero, returning false otherwise. Does not block or wait.

Parameters

sema	Semaphore to decrement

Returns

true if the count was decremented, false if it was already zero

Definition at line 87 of file sema.h.

semaTryDecTimeout()

bool semaTryDecTimeout	(	Semaphore *	sema,
		int64	timeout
	)

Attempt to decrement a semaphore with a timeout

Waits up to the specified timeout for the count to become greater than zero, then decrements it. Uses adaptive spinning before falling back to kernel waits for efficiency.

Parameters

sema	Semaphore to decrement
timeout	Maximum time to wait in nanoseconds (use timeForever for infinite)

Returns

true if the count was decremented, false if the timeout elapsed

Referenced by semaDec().