synchronization.h File Reference

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

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

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.

Detailed Description

Thread synchronization primitives (mutexes, semaphores, events)

Function Documentation

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_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_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_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_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_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_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_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_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_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_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_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_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_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_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

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_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_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]	timeoutms	Maximum amount of milliseconds to wait for signal

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_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