sync.h File Reference

Common synchronization primitives. More...

#include <stdbool.h>

Typedefs
typedef struct Mutex_T	Mutex_T
	Mutual exclusion structure.
typedef Mutex_T *	Mutex
	Mutual exclusion instance.
typedef struct Cond_T	Cond_T
	Condition variable structure.
typedef Cond_T *	Cond
	Condition variable instance.

Functions
Mutex	createMutex ()
	Create a new mutex instance.
void	destroyMutex (Mutex mutex)
	Destroys mutex instance.
void	lockMutex (Mutex mutex)
	Locks the mutex, blocks if the mutex is not available.
void	unlockMutex (Mutex mutex)
	Unlocks locked mutex.
bool	tryLockMutex (Mutex mutex)
	Tries to lock the mutex.
const void *	getMutexNative (Mutex mutex)
	Returns pointer to the native mutex handle.
Cond	createCond ()
	Create a new condition variable instance.
void	destroyCond (Cond cond)
	Destroys condition variable instance.
void	signalCond (Cond cond)
	Notifies one waiting thread.
void	broadcastCond (Cond cond)
	Notifies all waiting threads.
void	waitCond (Cond cond, Mutex mutex)
	Blocks the current thread until the condition variable is awakened.
void	waitCondFor (Cond cond, Mutex mutex, double timeout)
	Blocks the current thread until the condition variable is awakened or after the specified timeout duration.
const void *	getCondNative (Cond cond)
	Returns pointer to the native condition variable handle.

Detailed Description

Common synchronization primitives.

Synchronization primitives are used for managing concurrent access to shared resources, preventing race conditions, and ensuring thread safety.

Function Documentation

createMutex()

Mutex createMutex

(

)

Create a new mutex instance.

Note

You should destroy created mutex instance manually.

The mutex is a synchronization primitive that can be used to protect shared data from being simultaneously accessed by multiple threads.

Returns

A new mutex instance on success, otherwise NULL.

destroyMutex()

void destroyMutex

(

Mutex

mutex

)

Destroys mutex instance.

Parameters

mutex

mutex instance or NULL

lockMutex()

void lockMutex

(

Mutex

mutex

)

Locks the mutex, blocks if the mutex is not available.

Locks the mutex. If another thread has already locked the mutex, a call to lock will block execution until the lock is acquired.

Warning

If lock is called by a thread that already owns the mutex, the behavior is undefined.

Parameters

mutex

mutex instance

unlockMutex()

void unlockMutex

(

Mutex

mutex

)

Unlocks locked mutex.

Warning

The mutex must be locked by the current thread of execution, otherwise, the behavior is undefined.

Parameters

mutex

mutex instance

tryLockMutex()

bool tryLockMutex

(

Mutex

mutex

)

Tries to lock the mutex.

This function is allowed to fail spuriously and return false even if the mutex is not currently locked by any other thread.

Parameters

mutex

mutex instance

Returns

True on successful lock acquisition, otherwise false.

getMutexNative()

const void * getMutexNative

(

Mutex

mutex

)

Returns pointer to the native mutex handle.

Warning

You should not free returned pointer or use it after mutex destruction.

Parameters

mutex

mutex instance

createCond()

Cond createCond

(

)

Create a new condition variable instance.

Note

You should destroy created condition variable instance manually.

The condition variable is a synchronization primitive used with a Mutex to block one or more threads until another thread both modifies a shared variable (the condition) and notifies the condition variable.

Returns

A new condition variable instance on success, otherwise NULL.

destroyCond()

void destroyCond

(

Cond

cond

)

Destroys condition variable instance.

Parameters

cond	condition variable instance or NULL

signalCond()

void signalCond

(

Cond

cond

)

Notifies one waiting thread.

If any threads are waiting on this cond, calling signal() unblocks one of the waiting threads.

Parameters

cond	condition variable instance

broadcastCond()

void broadcastCond

(

Cond

cond

)

Notifies all waiting threads.

Unblocks all threads currently waiting for this cond.

Parameters

cond	condition variable instance

waitCond()

void waitCond	(	Cond	cond,
		Mutex	mutex )

Blocks the current thread until the condition variable is awakened.

Wait causes the current thread to block until the condition variable is notified or a spurious wakeup occurs.

Parameters

cond	condition variable instance
mutex	mutex instance

waitCondFor()

void waitCondFor	(	Cond	cond,
		Mutex	mutex,
		double	timeout )

Blocks the current thread until the condition variable is awakened or after the specified timeout duration.

Parameters

cond	condition variable instance
mutex	mutex instance
timeout	timeout time (in seconds)

getCondNative()

const void * getCondNative

(

Cond

cond

)

Returns pointer to the native condition variable handle.

Warning

You should not free returned pointer or use it after cond destruction.

Parameters

cond	condition variable instance