sem

Semaphore API for restricting access to a resource. More...

Functions
void	sem_init (semaphore_t *sem, int16_t initial_permits, int16_t max_permits)
	Initialise a semaphore structure. More...
int	sem_available (semaphore_t *sem)
	Return number of available permits on the semaphore. More...
bool	sem_release (semaphore_t *sem)
	Release a permit on a semaphore. More...
void	sem_reset (semaphore_t *sem, int16_t permits)
	Reset semaphore to a specific number of available permits. More...
void	sem_acquire_blocking (semaphore_t *sem)
	Acquire a permit from the semaphore. More...
bool	sem_acquire_timeout_ms (semaphore_t *sem, uint32_t timeout_ms)
	Acquire a permit from a semaphore, with timeout. More...
bool	sem_acquire_timeout_us (semaphore_t *sem, uint32_t timeout_us)
	Acquire a permit from a semaphore, with timeout. More...
bool	sem_acquire_block_until (semaphore_t *sem, absolute_time_t until)
	Wait to acquire a permit from a semaphore until a specific time. More...
bool	sem_try_acquire (semaphore_t *sem)
	Attempt to acquire a permit from a semaphore without blocking. More...

Detailed Description

Semaphore API for restricting access to a resource.

A semaphore holds a number of available permits. sem_acquire methods will acquire a permit if available (reducing the available count by 1) or block if the number of available permits is 0. sem_release() increases the number of available permits by one potentially unblocking a sem_acquire method.

Note that sem_release() may be called an arbitrary number of times, however the number of available permits is capped to the max_permit value specified during semaphore initialization.

Although these semaphore related functions can be used from IRQ handlers, it is obviously preferable to only release semaphores from within an IRQ handler (i.e. avoid blocking)

Function Documentation

sem_acquire_block_until()

bool sem_acquire_block_until	(	semaphore_t *	sem,
		absolute_time_t	until
	)

Wait to acquire a permit from a semaphore until a specific time.

This function will block and wait if no permits are available, until the specified timeout time. If the timeout is reached the function will return false, otherwise it will return true.

Parameters

sem	Pointer to semaphore structure
until	The time after which to return if the sem is not available.

Returns

true if permit was acquired, false if the until time was reached before acquiring.

sem_acquire_blocking()

void sem_acquire_blocking

(

semaphore_t *

sem

)

Acquire a permit from the semaphore.

This function will block and wait if no permits are available.

Parameters

sem	Pointer to semaphore structure

sem_acquire_timeout_ms()

bool sem_acquire_timeout_ms	(	semaphore_t *	sem,
		uint32_t	timeout_ms
	)

Acquire a permit from a semaphore, with timeout.

This function will block and wait if no permits are available, until the defined timeout has been reached. If the timeout is reached the function will return false, otherwise it will return true.

Parameters

sem	Pointer to semaphore structure
timeout_ms	Time to wait to acquire the semaphore, in milliseconds.

Returns

false if timeout reached, true if permit was acquired.

sem_acquire_timeout_us()

bool sem_acquire_timeout_us	(	semaphore_t *	sem,
		uint32_t	timeout_us
	)

Acquire a permit from a semaphore, with timeout.

This function will block and wait if no permits are available, until the defined timeout has been reached. If the timeout is reached the function will return false, otherwise it will return true.

Parameters

sem	Pointer to semaphore structure
timeout_us	Time to wait to acquire the semaphore, in microseconds.

Returns

false if timeout reached, true if permit was acquired.

sem_available()

int sem_available

(

semaphore_t *

sem

)

Return number of available permits on the semaphore.

Parameters

sem	Pointer to semaphore structure

Returns

The number of permits available on the semaphore.

sem_init()

void sem_init	(	semaphore_t *	sem,
		int16_t	initial_permits,
		int16_t	max_permits
	)

Initialise a semaphore structure.

Parameters

sem	Pointer to semaphore structure
initial_permits	How many permits are initially acquired
max_permits	Total number of permits allowed for this semaphore

sem_release()

bool sem_release

(

semaphore_t *

sem

)

Release a permit on a semaphore.

Increases the number of permits by one (unless the number of permits is already at the maximum). A blocked sem_acquire will be released if the number of permits is increased.

Parameters

sem	Pointer to semaphore structure

Returns

true if the number of permits available was increased.

sem_reset()

void sem_reset	(	semaphore_t *	sem,
		int16_t	permits
	)

Reset semaphore to a specific number of available permits.

Reset value should be from 0 to the max_permits specified in the init function

Parameters

sem	Pointer to semaphore structure
permits	the new number of available permits

sem_try_acquire()

bool sem_try_acquire

(

semaphore_t *

sem

)

Attempt to acquire a permit from a semaphore without blocking.

This function will return false without blocking if no permits are available, otherwise it will acquire a permit and return true.

Parameters

sem	Pointer to semaphore structure

Returns

true if permit was acquired.