OSAPI Semaphore

Abstract Semaphore API. More...

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 sempahore was not signaled before the timeout expired, waiting for the semaphore to unblock timed out, OSAPI_Semaphore_take 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

Abstract Semaphore API.

---

Macro Definition Documentation

#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 sempahore was not signaled before the timeout expired, waiting for the semaphore to unblock timed out, OSAPI_Semaphore_take 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.

---

Typedef Documentation

typedef struct OSAPI_Semaphore OSAPI_Semaphore_T

Abstract Semaphore type.

---

Function Documentation

OSAPI_Semaphore_T* OSAPI_Semaphore_new

(

void

)

Create a Semaphore.

The created semaphore is a binary semaphore with an initial semaphore value set to 0 and a maximum value of 1. Thus, a call to OSAPI_Semaphore_take will block until the semaphore is signaled with a call to OSAPI_Semaphore_give.

Returns:

Pointer to a semaphore with a value of 1 on success, NULL on failure.

RTI_BOOL OSAPI_Semaphore_delete

(

OSAPI_Semaphore_T *

self

)

Delete a semaphore.

Parameters:

[in]

self

Semaphore created with OSAPI_Semaphore_new.

Returns:

RTI_TRUE on success, RTI_FALSE on failure.

See Also OSAPI_Semaphore_new

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

Take a Semaphore.

Parameters:

[in]	self	Semaphore previously created with OSAPI_Semaphore_new.
[in]	timeout_ms	Timeout in ms. The take call will wait at most timeout ms before returning. If OSAPI_SEMAPHORE_TIMEOUT_INFINITE is specified, the call will not return until the semaphore has a value of 1 or higher.
[out]	fail_reason	Additional information when the call returns. If RTI_TRUE is returned, but timed out, fail_reason is set to OSAPI_SEMAPHORE_RESULT_TIMEOUT, otherwise fail_reason is set to OSAPI_SEMAPHORE_RESULT_OK. If RTI_FALSE is returned, fail_reason is set toOSAPI_SEMAPHORE_RESULT_ERROR.

Returns:

RTI_TRUE on success, RTI_FALSE on failure.

RTI_BOOL OSAPI_Semaphore_give

(

OSAPI_Semaphore_T *

self

)

Give a Semaphore.

A mutex can only be given if it is owned by the calling thread. The mutex must be given as many times as it has been taken.

Parameters:

[in]

self

Semaphore previously created with OSAPI_Semaphore_new.

Returns:

RTI_TRUE on success, RTI_FALSE on failure.