Synchronization.h File Reference

Go to the source code of this file.

Typedefs
typedef unsigned int	WPI_Handle
	Generic handle for all WPI handle-based interfaces. More...
typedef WPI_Handle	WPI_EventHandle
	An event handle. More...
typedef WPI_Handle	WPI_SemaphoreHandle
	A semaphore handle. More...

Functions
WPI_EventHandle	WPI_CreateEvent (int manual_reset, int initial_state)
	Creates an event. More...
void	WPI_DestroyEvent (WPI_EventHandle handle)
	Destroys an event. More...
void	WPI_SetEvent (WPI_EventHandle handle)
	Sets an event to signaled state. More...
void	WPI_ResetEvent (WPI_EventHandle handle)
	Sets an event to non-signaled state. More...
WPI_SemaphoreHandle	WPI_CreateSemaphore (int initial_count, int maximum_count)
	Creates a semaphore. More...
void	WPI_DestroySemaphore (WPI_SemaphoreHandle handle)
	Destroys a semaphore. More...
int	WPI_ReleaseSemaphore (WPI_SemaphoreHandle handle, int release_count, int *prev_count)
	Releases N counts of a semaphore. More...
int	WPI_WaitForObject (WPI_Handle handle)
	Waits for an handle to be signaled. More...
int	WPI_WaitForObjectTimeout (WPI_Handle handle, double timeout, int *timed_out)
	Waits for an handle to be signaled, with timeout. More...
int	WPI_WaitForObjects (const WPI_Handle *handles, int handles_count, WPI_Handle *signaled)
	Waits for one or more handles to be signaled. More...
int	WPI_WaitForObjectsTimeout (const WPI_Handle *handles, int handles_count, WPI_Handle *signaled, double timeout, int *timed_out)
	Waits for one or more handles to be signaled, with timeout. More...
void	WPI_CreateSignalObject (WPI_Handle handle, int manual_reset, int initial_state)
	Sets up signaling for an arbitrary handle. More...
void	WPI_SetSignalObject (WPI_Handle handle)
	Sets a handle to signaled state. More...
void	WPI_ResetSignalObject (WPI_Handle handle)
	Sets a handle to non-signaled state. More...
void	WPI_DestroySignalObject (WPI_Handle handle)
	Cleans up signaling for a handle. More...

Typedef Documentation

WPI_EventHandle

typedef WPI_Handle WPI_EventHandle

An event handle.

WPI_Handle

typedef unsigned int WPI_Handle

Generic handle for all WPI handle-based interfaces.

Handle data layout:

• Bits 0-23: Type-specific
• Bits 24-30: Type
• Bit 31: Error

WPI_SemaphoreHandle

typedef WPI_Handle WPI_SemaphoreHandle

A semaphore handle.

Function Documentation

WPI_CreateEvent()

WPI_EventHandle WPI_CreateEvent	(	int	manual_reset,
		int	initial_state
	)

Creates an event.

Events have binary state (signaled or not signaled) and may be either automatically reset or manually reset. Automatic-reset events go to non-signaled state when a WaitForObject is woken up by the event; manual-reset events require ResetEvent() to be called to set the event to non-signaled state; if ResetEvent() is not called, any waiter on that event will immediately wake when called.

Parameters

manual_reset	true for manual reset, false for automatic reset
initial_state	true to make the event initially in signaled state

Returns

Event handle

WPI_CreateSemaphore()

WPI_SemaphoreHandle WPI_CreateSemaphore	(	int	initial_count,
		int	maximum_count
	)

Creates a semaphore.

Semaphores keep an internal counter. Releasing the semaphore increases the count. A semaphore with a non-zero count is considered signaled. When a waiter wakes up it atomically decrements the count by 1. This is generally useful in a single-supplier, multiple-consumer scenario.

Parameters

initial_count	initial value for the semaphore's internal counter
maximum_count	maximum value for the samephore's internal counter

Returns

Semaphore handle

WPI_CreateSignalObject()

void WPI_CreateSignalObject	(	WPI_Handle	handle,
		int	manual_reset,
		int	initial_state
	)

Sets up signaling for an arbitrary handle.

With this function, any handle can operate like an event handle.

Parameters

handle	handle
manual_reset	true for manual reset, false for automatic reset
initial_state	true to make the handle initially in signaled state

WPI_DestroyEvent()

void WPI_DestroyEvent

(

WPI_EventHandle

handle

)

Destroys an event.

Destruction wakes up any waiters.

Parameters

handle

event handle

WPI_DestroySemaphore()

void WPI_DestroySemaphore

(

WPI_SemaphoreHandle

handle

)

Destroys a semaphore.

Destruction wakes up any waiters.

Parameters

handle

semaphore handle

WPI_DestroySignalObject()

void WPI_DestroySignalObject

(

WPI_Handle

handle

)

Cleans up signaling for a handle.

Destruction wakes up any waiters.

Parameters

handle

handle

WPI_ReleaseSemaphore()

int WPI_ReleaseSemaphore	(	WPI_SemaphoreHandle	handle,
		int	release_count,
		int *	prev_count
	)

Releases N counts of a semaphore.

Parameters

handle	semaphore handle
release_count	amount to add to semaphore's internal counter; must be positive
prev_count	if non-null, previous count (output parameter)

Returns

Non-zero on successful release, zero on failure (e.g. release count would exceed maximum value, or handle invalid)

WPI_ResetEvent()

void WPI_ResetEvent

(

WPI_EventHandle

handle

)

Sets an event to non-signaled state.

Parameters

handle

event handle

WPI_ResetSignalObject()

void WPI_ResetSignalObject

(

WPI_Handle

handle

)

Sets a handle to non-signaled state.

Parameters

handle

handle

WPI_SetEvent()

void WPI_SetEvent

(

WPI_EventHandle

handle

)

Sets an event to signaled state.

Parameters

handle

event handle

WPI_SetSignalObject()

void WPI_SetSignalObject

(

WPI_Handle

handle

)

Sets a handle to signaled state.

Parameters

handle

handle

WPI_WaitForObject()

int WPI_WaitForObject

(

WPI_Handle

handle

)

Waits for an handle to be signaled.

Parameters

handle

handle to wait on

Returns

Non-zero if handle was signaled, zero otherwise (e.g. object was destroyed)

WPI_WaitForObjects()

int WPI_WaitForObjects	(	const WPI_Handle *	handles,
		int	handles_count,
		WPI_Handle *	signaled
	)

Waits for one or more handles to be signaled.

Invalid handles are treated as signaled; the returned array will have the handle error bit set for any invalid handles.

Parameters

handles	array of handles to wait on
handles_count	length of the handles array
signaled	output array for storage of signaled handles; must be at least the size of the handles input array

Returns

number of signaled handles

WPI_WaitForObjectsTimeout()

int WPI_WaitForObjectsTimeout	(	const WPI_Handle *	handles,
		int	handles_count,
		WPI_Handle *	signaled,
		double	timeout,
		int *	timed_out
	)

Waits for one or more handles to be signaled, with timeout.

Invalid handles are treated as signaled; the returned array will have the handle error bit set for any invalid handles.

Parameters

handles	array of handles to wait on
handles_count	length of the handles array
signaled	output array for storage of signaled handles; must be at least the size of the handles input array
timeout	timeout in seconds
timed_out	if non-null, set to non-zero if timeout reached without any handle being signaled; set to zero otherwise (output)

Returns

number of signaled handles

WPI_WaitForObjectTimeout()

int WPI_WaitForObjectTimeout	(	WPI_Handle	handle,
		double	timeout,
		int *	timed_out
	)

Waits for an handle to be signaled, with timeout.

Parameters

handle	handle to wait on
timeout	timeout in seconds
timed_out	if non-null, set to non-zero if timeout reached without handle being signaled; set to zero otherwise (output)

Returns

Non-zero if handle was signaled, zero otherwise (e.g. object was destroyed or timed out)