Semaphores

Collaboration diagram for Semaphores:

Description

Semaphore API.

Classes
struct	ar_semaphore_t
	Counting semaphore. More...
class	Ar::Semaphore
	Counting semaphore class. More...

Semaphores
ar_status_t	ar_semaphore_create (ar_semaphore_t *sem, const char *name, unsigned count)
	Create a new semaphore. More...
ar_status_t	ar_semaphore_delete (ar_semaphore_t *sem)
	Delete a semaphore. More...
ar_status_t	ar_semaphore_get (ar_semaphore_t *sem, uint32_t timeout)
	Acquire the semaphore. More...
ar_status_t	ar_semaphore_put (ar_semaphore_t *sem)
	Release the semaphore. More...
uint32_t	ar_semaphore_get_count (ar_semaphore_t *sem)
	Returns the current semaphore count. More...
const char *	ar_semaphore_get_name (ar_semaphore_t *sem)
	Get the semaphore's name. More...

---

Class Documentation

ar_semaphore_t

struct ar_semaphore_t

Collaboration diagram for ar_semaphore_t:

Class Members
ar_list_t	m_blockedList	List of threads blocked on the semaphore.
volatile unsigned	m_count	Current semaphore count. Value of 0 means the semaphore is owned.
const char *	m_name	Name of the semaphore.

Function Documentation

ar_semaphore_create()

ar_status_t ar_semaphore_create	(	ar_semaphore_t *	sem,
		const char *	name,
		unsigned	count
	)

Create a new semaphore.

Parameters

sem	Pointer to storage for the semaphore.
name	Pass a name for the semaphore. If NULL is passed the name will be set to an empty string.
count	The initial semaphore count. Setting this value to 0 will cause the first call to get() to block until put() is called. A value of 1 or greater will allow that many calls to get() to succeed.

Return values

kArSuccess

Semaphore initialised successfully.

ar_semaphore_delete()

ar_status_t ar_semaphore_delete

(

ar_semaphore_t *

sem

)

Delete a semaphore.

Any threads on the blocked list will be unblocked immediately. Their return status from the get function will be kArObjectDeletedError.

Parameters

sem	Pointer to the semaphore.

Return values

kArSuccess

Semaphore deleted successfully.

ar_semaphore_get()

ar_status_t ar_semaphore_get	(	ar_semaphore_t *	sem,
		uint32_t	timeout
	)

Acquire the semaphore.

The semaphore count is decremented. If the count is 0 upon entering this method then the caller thread is blocked until the count reaches 1. Threads are unblocked in the order in which they were blocked. Priority is not taken into consideration, so priority inversions are possible.

Note

This function may be called from interrupt context only if the timeout parameter is set to kArNoTimeout (or 0).

Parameters

sem	Pointer to the semaphore.
timeout	The maximum number of milliseconds that the caller is willing to wait in a blocked state before the semaphore can be obtained. If this value is 0, or kArNoTimeout, then this method will return immediately if the semaphore cannot be obtained. Setting the timeout to kArInfiniteTimeout will cause the thread to wait forever for a chance to get the semaphore.

Return values

kArSuccess	The semaphore was obtained without error.
kArTimeoutError	The specified amount of time has elapsed before the semaphore could be obtained.
kArObjectDeletedError	Another thread deleted the semaphore while the caller was blocked on it.
kArNotFromInterruptError	A non-zero timeout is not alllowed from the interrupt context.

ar_semaphore_get_count()

uint32_t ar_semaphore_get_count

(

ar_semaphore_t *

sem

)

Returns the current semaphore count.

Parameters

sem	Pointer to the semaphore.

ar_semaphore_get_name()

const char* ar_semaphore_get_name

(

ar_semaphore_t *

sem

)

Get the semaphore's name.

Parameters

sem	Pointer to the semaphore.

ar_semaphore_put()

ar_status_t ar_semaphore_put

(

ar_semaphore_t *

sem

)

Release the semaphore.

The semaphore count is incremented.

Parameters

sem	Pointer to the semaphore.

Note

This call is safe from interrupt context.