Thread synchronization primitives (mutexes, semaphores, events) More...

#include "gate/gate_core_api.h"
#include "gate/gatetypes.h"
#include "gate/results.h"
#include "gate/handles.h"
#include "gate/memalloc.h"
#include "gate/streams.h"

Classes
struct	gate_mutex

Typedefs
typedef struct gate_mutex	gate_mutex_t

typedef gate_handlestore_t	gate_semaphore_t

typedef gate_handlestore_t	gate_syncevent_t

typedef gate_handlestore_t	gate_synccondition_t

typedef void *	gate_future_t

Functions
GATE_CORE_API gate_result_t	gate_mutex_create (gate_mutex_t *mutex)
	Creates and initializes MUTEX object.

GATE_CORE_API gate_result_t	gate_mutex_acquire (gate_mutex_t *mutex)
	Acquires the MUTEX for the current thread (blocks if the MUTEX is acquired by another thread)

GATE_CORE_API gate_result_t	gate_mutex_release (gate_mutex_t *mutex)
	Releases the MUTEX in a thread that had acquired it.

GATE_CORE_API gate_result_t	gate_mutex_destroy (gate_mutex_t *mutex)
	Deletes the allocated ressources of a MUTEX.

GATE_CORE_API gate_result_t	gate_semaphore_create (gate_semaphore_t *semaphore, gate_uint32_t count)
	Creates a new SEMAPHORE object and initializes it with the given counter maximum value.

GATE_CORE_API gate_result_t	gate_semaphore_acquire (gate_semaphore_t *semaphore)
	Blocks until the SEMAPHORE's counter is greater than zero and than decreases it by 1.

GATE_CORE_API gate_result_t	gate_semaphore_timed_acquire (gate_semaphore_t *semaphore, gate_uint32_t timeoutms)
	Blocks until the SEMAPHORE's counter is greater than zero and than decreases it by 1, or cancels if the given timeout is reached.

GATE_CORE_API gate_result_t	gate_semaphore_release (gate_semaphore_t *semaphore)
	Increments the SEMAPHORE's counter by one (and wakes up waiting threads if the counter was at 0)

GATE_CORE_API gate_result_t	gate_semaphore_destroy (gate_semaphore_t *semaphore)
	Deletes all allocated resources of a SEMAPHORE object.

GATE_CORE_API gate_result_t	gate_syncevent_create (gate_syncevent_t *syncevent, gate_bool_t autoreset)
	Creates a SYNCHRONIZATION EVENT object and enables or disables its AUTORESET feature.

GATE_CORE_API gate_result_t	gate_syncevent_destroy (gate_syncevent_t *syncevent)
	Deletes all allocated resources of a SYNCHRONIZATION EVENT object.

GATE_CORE_API gate_result_t	gate_syncevent_set (gate_syncevent_t *syncevent)
	Enables the synchronization signal to wake up waiting threads.

GATE_CORE_API gate_result_t	gate_syncevent_reset (gate_syncevent_t *syncevent)
	Disables the synchronization signal to keep waiting threads sleeping.

GATE_CORE_API gate_result_t	gate_syncevent_wait (gate_syncevent_t *syncevent)
	Blocks the current thread until a synchronization signal was set by another thread.

GATE_CORE_API gate_result_t	gate_syncevent_timed_wait (gate_syncevent_t *syncevent, gate_uint32_t timeoutms)
	Blocks the current thread until a synchronization signal was set by another thread, or if the timeout in milliseconds was reached.

GATE_CORE_API gate_result_t	gate_syncmemstream_create (gate_size_t prealloc, gate_uint32_t timeoutms, gate_stream_t **ptrtostream)
	Creates a synchronized memory stream that blocks reading until data was written from another thread.

GATE_CORE_API gate_result_t	gate_synccondition_create (gate_synccondition_t *cond)
	Creates a condition variable that can emit and wait for signals from other threads.

GATE_CORE_API gate_result_t	gate_synccondition_destroy (gate_synccondition_t *cond)
	Releases resources of condition variable.

GATE_CORE_API gate_result_t	gate_synccondition_wait (gate_synccondition_t cond, gate_mutex_t mutex)
	Waits on condition variable until signal arrives.

GATE_CORE_API gate_result_t	gate_synccondition_timed_wait (gate_synccondition_t cond, gate_mutex_t mutex, gate_uint32_t timeoutms)
	Waits on condition variable until signal arrives or timeout is reached.

GATE_CORE_API gate_result_t	gate_synccondition_signal_one (gate_synccondition_t *cond)
	Wakes up one thread waiting on condition variable.

GATE_CORE_API gate_result_t	gate_synccondition_signal_all (gate_synccondition_t *cond)
	Wakes up all threads waiting on condition variable.

GATE_CORE_API gate_result_t	gate_future_create (gate_future_t *future, gate_size_t sz, gate_mem_copyctor_t cctor, gate_mem_dtor_t dtor)

GATE_CORE_API gate_result_t	gate_future_retain (gate_future_t future, gate_future_t const src)

GATE_CORE_API gate_result_t	gate_future_release (gate_future_t *future)

GATE_CORE_API void *	gate_future_get_data_ptr (gate_future_t *future)

GATE_CORE_API gate_result_t	gate_future_set_result (gate_future_t future, gate_result_t result, void const data)

GATE_CORE_API gate_bool_t	gate_future_available (gate_future_t const *future)

GATE_CORE_API gate_result_t	gate_future_await_timed (gate_future_t *future, gate_uint32_t timeout_ms)

GATE_CORE_API gate_result_t	gate_future_await (gate_future_t *future)

GATE_CORE_API gate_result_t	gate_future_get_result (gate_future_t const *future)

GATE_CORE_API void const *	gate_future_get_data (gate_future_t const *future)

Detailed Description

Thread synchronization primitives (mutexes, semaphores, events)

Function Documentation

◆ gate_mutex_acquire()

GATE_CORE_API gate_result_t gate_mutex_acquire ( gate_mutex_t * mutex )

Acquires the MUTEX for the current thread (blocks if the MUTEX is acquired by another thread)

Parameters

[in] mutex Pointer to MUTEX object

Returns: GATE_RESULT_* success or error code

◆ gate_mutex_create()

GATE_CORE_API gate_result_t gate_mutex_create ( gate_mutex_t * mutex )

Creates and initializes MUTEX object.

Parameters

[in,out] mutex Pointer to MUTEX object

Returns: GATE_RESULT_* success or error code

◆ gate_mutex_destroy()

GATE_CORE_API gate_result_t gate_mutex_destroy ( gate_mutex_t * mutex )

Deletes the allocated ressources of a MUTEX.

Parameters

[in] mutex Pointer to MUTEX object

Returns: GATE_RESULT_* success or error code

◆ gate_mutex_release()

GATE_CORE_API gate_result_t gate_mutex_release ( gate_mutex_t * mutex )

Releases the MUTEX in a thread that had acquired it.

Parameters

[in] mutex Pointer to MUTEX object

Returns: GATE_RESULT_* success or error code

◆ gate_semaphore_acquire()

GATE_CORE_API gate_result_t gate_semaphore_acquire ( gate_semaphore_t * semaphore )

Blocks until the SEMAPHORE's counter is greater than zero and than decreases it by 1.

Parameters

[in] semaphore Pointer to SEMAPHORE object

Returns: GATE_RESULT_* success or error code

◆ gate_semaphore_create()

GATE_CORE_API gate_result_t gate_semaphore_create	(	gate_semaphore_t *	semaphore,
		gate_uint32_t	count )

Creates a new SEMAPHORE object and initializes it with the given counter maximum value.

Parameters

[in,out]	semaphore	Pointer to SEMAPHORE object
[in]	count	Maximum count value of the SEMAPHORE

Returns: GATE_RESULT_* success or error code

◆ gate_semaphore_destroy()

GATE_CORE_API gate_result_t gate_semaphore_destroy ( gate_semaphore_t * semaphore )

Deletes all allocated resources of a SEMAPHORE object.

Parameters

[in] semaphore Pointer to SEMAPHORE object

Returns: GATE_RESULT_* success or error code

◆ gate_semaphore_release()

GATE_CORE_API gate_result_t gate_semaphore_release ( gate_semaphore_t * semaphore )

Increments the SEMAPHORE's counter by one (and wakes up waiting threads if the counter was at 0)

Parameters

[in] semaphore Pointer to SEMAPHORE object

Returns: GATE_RESULT_* success or error code

◆ gate_semaphore_timed_acquire()

GATE_CORE_API gate_result_t gate_semaphore_timed_acquire	(	gate_semaphore_t *	semaphore,
		gate_uint32_t	timeoutms )

Blocks until the SEMAPHORE's counter is greater than zero and than decreases it by 1, or cancels if the given timeout is reached.

Parameters

[in]	semaphore	Pointer to SEMAPHORE object
[in]	timeoutms	Maximum amount of milliseconds to wait while the counter is not greater than 1

Returns: GATE_RESULT_* success or error code, GATE_RESULT_TIMEOUT indicates a timeout

◆ gate_synccondition_create()

GATE_CORE_API gate_result_t gate_synccondition_create ( gate_synccondition_t * cond )

Creates a condition variable that can emit and wait for signals from other threads.

Parameters

[in,out] cond Pointer to conditional variable to be created

Returns: GATE_RESULT_* success or error code

◆ gate_synccondition_destroy()

GATE_CORE_API gate_result_t gate_synccondition_destroy ( gate_synccondition_t * cond )

Releases resources of condition variable.

Parameters

[in] cond Pointer to conditional variable to be accessed

Returns: GATE_RESULT_* success or error code

◆ gate_synccondition_signal_all()

GATE_CORE_API gate_result_t gate_synccondition_signal_all ( gate_synccondition_t * cond )

Wakes up all threads waiting on condition variable.

Parameters

[in] cond Pointer to conditional variable to be accessed

Returns: GATE_RESULT_* success or error code

◆ gate_synccondition_signal_one()

GATE_CORE_API gate_result_t gate_synccondition_signal_one ( gate_synccondition_t * cond )

Wakes up one thread waiting on condition variable.

Parameters

[in] cond Pointer to conditional variable to be accessed

Returns: GATE_RESULT_* success or error code

◆ gate_synccondition_timed_wait()

GATE_CORE_API gate_result_t gate_synccondition_timed_wait	(	gate_synccondition_t *	cond,
		gate_mutex_t *	mutex,
		gate_uint32_t	timeoutms )

Waits on condition variable until signal arrives or timeout is reached.

Parameters

[in]	cond	Pointer to conditional variable to be accessed
[in]	mutex	Pointer to locked mutex to be unlocked during wait state
[in]	cond	Maximum amount of milliseconds to wait for signal

Returns: GATE_RESULT_* success or error code

◆ gate_synccondition_wait()

GATE_CORE_API gate_result_t gate_synccondition_wait	(	gate_synccondition_t *	cond,
		gate_mutex_t *	mutex )

Waits on condition variable until signal arrives.

Parameters

[in]	cond	Pointer to conditional variable to be accessed
[in]	mutex	Pointer to locked mutex to be unlocked during wait state

Returns: GATE_RESULT_* success or error code

◆ gate_syncevent_create()

GATE_CORE_API gate_result_t gate_syncevent_create	(	gate_syncevent_t *	syncevent,
		gate_bool_t	autoreset )

Creates a SYNCHRONIZATION EVENT object and enables or disables its AUTORESET feature.

Parameters

[in,out]	syncevent	Pointer to SYNCHRONIZATION EVENT object
	autoreset	If 'true', an event automatically resets itself, if one thread was woken up by it

Returns: GATE_RESULT_* success or error code

◆ gate_syncevent_destroy()

GATE_CORE_API gate_result_t gate_syncevent_destroy ( gate_syncevent_t * syncevent )

Deletes all allocated resources of a SYNCHRONIZATION EVENT object.

Parameters

[in] syncevent Pointer to SYNCHRONIZATION EVENT object

Returns: GATE_RESULT_* success or error code

◆ gate_syncevent_reset()

GATE_CORE_API gate_result_t gate_syncevent_reset ( gate_syncevent_t * syncevent )

Disables the synchronization signal to keep waiting threads sleeping.

Parameters

[in] syncevent Pointer to SYNCHRONIZATION EVENT object

Returns: GATE_RESULT_* success or error code

◆ gate_syncevent_set()

GATE_CORE_API gate_result_t gate_syncevent_set ( gate_syncevent_t * syncevent )

Enables the synchronization signal to wake up waiting threads.

Parameters

[in] syncevent Pointer to SYNCHRONIZATION EVENT object

Returns: GATE_RESULT_* success or error code

◆ gate_syncevent_timed_wait()

GATE_CORE_API gate_result_t gate_syncevent_timed_wait	(	gate_syncevent_t *	syncevent,
		gate_uint32_t	timeoutms )

Blocks the current thread until a synchronization signal was set by another thread, or if the timeout in milliseconds was reached.

Parameters

[in]	syncevent	Pointer to SYNCHRONIZATION EVENT object
[in]	timeoutms	Maximum amout of milliseconds to wait for a synchronization signal

Returns: GATE_RESULT_* success or error code, GATE_RESULT_TIMEOUT indicates a timeout

◆ gate_syncevent_wait()

GATE_CORE_API gate_result_t gate_syncevent_wait ( gate_syncevent_t * syncevent )

Blocks the current thread until a synchronization signal was set by another thread.

Parameters

[in] syncevent Pointer to SYNCHRONIZATION EVENT object

Returns: GATE_RESULT_* success or error code

◆ gate_syncmemstream_create()

GATE_CORE_API gate_result_t gate_syncmemstream_create	(	gate_size_t	prealloc,
		gate_uint32_t	timeoutms,
		gate_stream_t **	ptrtostream )

Creates a synchronized memory stream that blocks reading until data was written from another thread.

Parameters

[in]	prealloc	Amount of bytes to preallocate in the internal buffer
[in]	timeoutms	Maximum amout of milliseconds to wait for a read() operation if no data was written to the stream
[out]	ptrtostream	Pointer to output variable that receives the stream pointer

Returns: GATE_RESULT_* success or error code

Classes

Typedefs

Functions

Detailed Description

Function Documentation

◆ gate_mutex_acquire()

◆ gate_mutex_create()

◆ gate_mutex_destroy()

◆ gate_mutex_release()

◆ gate_semaphore_acquire()

◆ gate_semaphore_create()

◆ gate_semaphore_destroy()

◆ gate_semaphore_release()

◆ gate_semaphore_timed_acquire()

◆ gate_synccondition_create()

◆ gate_synccondition_destroy()

◆ gate_synccondition_signal_all()

◆ gate_synccondition_signal_one()

◆ gate_synccondition_timed_wait()

◆ gate_synccondition_wait()

◆ gate_syncevent_create()

◆ gate_syncevent_destroy()

◆ gate_syncevent_reset()

◆ gate_syncevent_set()

◆ gate_syncevent_timed_wait()

◆ gate_syncevent_wait()

◆ gate_syncmemstream_create()