osapi_semaphore.h File Reference

Semaphore interface definition. More...

#include "osapi/osapi_dll.h"
#include "osapi/osapi_types.h"

Macros
#define	OSAPI_SEMAPHORE_TIMEOUT_INFINITE   -1
	If OSAPI_Semaphore_take is called with OSAPI_SEMAPHORE_TIMEOUT_INFINITE as timeout, OSAPI_Semaphore_take will not return until the semaphore is signaled.
#define	OSAPI_SEMAPHORE_RESULT_OK   0
	If OSAPI_Semaphore_take succeeds and the semaphore is signaled within the timeout period, OSAPI_Semaphore_take returns TRUE and sets the failure reason to OSAPI_SEMAPHORE_RESULT_OK.
#define	OSAPI_SEMAPHORE_RESULT_TIMEOUT   1
	If OSAPI_Semaphore_take was called with a timeout value different from OSAPI_SEMAPHORE_TIMEOUT_INFINITE, and the semaphore was not signaled before the timeout expired, OSAPI_Semaphore_take returns TRUE and sets the failure reason to OSAPI_SEMAPHORE_RESULT_TIMEOUT.
#define	OSAPI_SEMAPHORE_RESULT_ERROR   2
	If OSAPI_Semaphore_take fails for an unknown reason, OSAPI_Semaphore_take returns FALSE and sets the failure reason to OSAPI_SEMAPHORE_RESULT_ERROR.

Typedefs
typedef struct OSAPI_Semaphore	OSAPI_Semaphore_T
	Abstract Semaphore type.

Functions
OSAPI_Semaphore_T *	OSAPI_Semaphore_new (void)
	Create a Semaphore.
RTI_BOOL	OSAPI_Semaphore_delete (OSAPI_Semaphore_T *self)
	Delete a semaphore.
RTI_BOOL	OSAPI_Semaphore_take (OSAPI_Semaphore_T *self, RTI_INT32 timeout_ms, RTI_INT32 *fail_reason)
	Take a Semaphore.
RTI_BOOL	OSAPI_Semaphore_give (OSAPI_Semaphore_T *self)
	Give a Semaphore.

Detailed Description

Semaphore interface definition.

Function Documentation

OSAPI_Semaphore_new()

OSAPI_Semaphore_T * OSAPI_Semaphore_new

(

void

)

Create a Semaphore.

Create a new binary semaphore with an initial count of 0 and a maximum count of 1. A call to OSAPI_Semaphore_take will block until the semaphore is signaled with a call to OSAPI_Semaphore_give.

The created semaphore must be deleted using OSAPI_Semaphore_delete when no longer needed (only available when RTI_CERT is not defined).

Returns

Pointer to a semaphore with an initial count of 0 on success, NULL on failure.

OSAPI_Semaphore_take()

RTI_BOOL OSAPI_Semaphore_take	(	OSAPI_Semaphore_T *	self,
		RTI_INT32	timeout_ms,
		RTI_INT32 *	fail_reason )

Take a Semaphore.

Wait for the semaphore to be signaled. If the semaphore count is greater than 0, this function decrements the count and returns immediately. Otherwise, it blocks until the semaphore is signaled by OSAPI_Semaphore_give or the timeout expires.

Parameters

self	<<in>> Semaphore previously created with OSAPI_Semaphore_new. Cannot be NULL.
timeout_ms	<<in>> Timeout in milliseconds. The take call will wait at most timeout_ms milliseconds before returning. If OSAPI_SEMAPHORE_TIMEOUT_INFINITE is specified, the call will not return until the semaphore count is 1 or higher.
fail_reason	<<out>> Additional information when the call returns. Cannot be NULL. If RTI_TRUE is returned and the semaphore was acquired, fail_reason is set to OSAPI_SEMAPHORE_RESULT_OK. If RTI_TRUE is returned but the operation timed out, fail_reason is set to OSAPI_SEMAPHORE_RESULT_TIMEOUT. If RTI_FALSE is returned, fail_reason is set to OSAPI_SEMAPHORE_RESULT_ERROR.

Returns

RTI_TRUE on success (including timeout), RTI_FALSE on error.

See Also OSAPI_Semaphore_give

References RTI_INT32.

OSAPI_Semaphore_give()

RTI_BOOL OSAPI_Semaphore_give

(

OSAPI_Semaphore_T *

self

)

Give a Semaphore.

Signal the semaphore by incrementing its count. If any threads are blocked waiting on this semaphore via OSAPI_Semaphore_take, one of them will be unblocked. A semaphore can only be given if it is owned by the calling thread.

Parameters

self	<<in>> Semaphore previously created with OSAPI_Semaphore_new. Cannot be NULL.

Returns

RTI_TRUE on success, RTI_FALSE on failure.

See Also OSAPI_Semaphore_take

References RTI_INT32, and RTI_UINT32.