Lightweight semaphore implementation. More...

Detailed Description

Lightweight semaphore implementation.

Modules
	sema_deprecated

Files
file	sema.h
	Semaphore definitions.

Data Structures
struct	sema_t
	A Semaphore. More...

Macros
#define	SEMA_CREATE(value) { (value), SEMA_OK, MUTEX_INIT }
	Creates semaphore statically. More...

#define	SEMA_CREATE_LOCKED() { (0), SEMA_OK, MUTEX_INIT_LOCKED }
	Creates semaphore statically initialized to 0. More...

Enumerations
enum	sema_state_t { SEMA_OK = 0 , SEMA_DESTROY }
	A Semaphore states.

Functions
void	sema_create (sema_t *sema, unsigned int value)
	Creates semaphore dynamically. More...

void	sema_destroy (sema_t *sema)
	Destroys a semaphore. More...

static unsigned	sema_get_value (const sema_t *sema)
	Get a semaphore's current value. More...

int	_sema_wait_ztimer (sema_t sema, int block, ztimer_clock_t clock, uint32_t timeout)
	Wait for a semaphore, blocking or non-blocking. More...

static int	sema_wait (sema_t *sema)
	Wait for a semaphore being posted (without timeout). More...

static int	sema_try_wait (sema_t *sema)
	Test if the semaphore is posted. More...

static int	sema_wait_timed (sema_t *sema, uint64_t timeout)
	Wait for a semaphore being posted with a 64bit timeout. More...

static int	sema_wait_timed_ztimer (sema_t sema, ztimer_clock_t clock, uint32_t timeout)
	Wait for a semaphore being posted, using ztimer as backend. More...

int	sema_post (sema_t *sema)
	Signal semaphore. More...

Macro Definition Documentation

◆ SEMA_CREATE

#define SEMA_CREATE ( value ) { (value), SEMA_OK, MUTEX_INIT }

Creates semaphore statically.

Parameters

[in] value Initial value for the semaphore (can't be 0). For a 0 initialized semaphore

See also: SEMA_CREATE_LOCKED

Returns: Statically initialized semaphore.

Definition at line 48 of file sema.h.

◆ SEMA_CREATE_LOCKED

#define SEMA_CREATE_LOCKED ( ) { (0), SEMA_OK, MUTEX_INIT_LOCKED }

Creates semaphore statically initialized to 0.

Returns: Statically initialized semaphore.

Definition at line 54 of file sema.h.

Function Documentation

◆ _sema_wait_ztimer()

int _sema_wait_ztimer	(	sema_t *	sema,
		int	block,
		ztimer_clock_t *	clock,
		uint32_t	timeout
	)

Wait for a semaphore, blocking or non-blocking.

For commit purposes you should probably use sema_wait(), sema_wait_timed_ztimer() and sema_try_wait() instead.

Precondition: (sema != NULL)

Parameters

[in]	sema	A semaphore.
[in]	block	if true, block until semaphore is available.
[in]	clock	ztimer clock
[in]	timeout	if blocking, ticks of `clock` until the semaphore times out. 0 waits forever.

Returns: 0 on success; -ETIMEDOUT, if the semaphore times out.; -ECANCELED, if the semaphore was destroyed.; -EAGAIN, if the semaphore is not posted (only if block = 0)

◆ sema_create()

void sema_create	(	sema_t *	sema,
		unsigned int	value
	)

Creates semaphore dynamically.

Precondition: (sema != NULL)

See also: The Open Group Base Specifications Issue 7, sem_init() (without pshared parameter)

Parameters

[out]	sema	The created semaphore.
[in]	value	Initial value for the semaphore.

◆ sema_destroy()

void sema_destroy ( sema_t * sema )

Destroys a semaphore.

Precondition: (sema != NULL)

See also: The Open Group Base Specifications Issue 7, sem_destroy()

Destroying a semaphore upon which other threads are currently blocked will wake the other threads causing the sema_wait (or sema_wait_timed) to return error (-ECANCELED).

Parameters

[in] sema The semaphore to destroy.

◆ sema_get_value()

static unsigned sema_get_value ( const sema_t * sema )

inlinestatic

Get a semaphore's current value.

Parameters

[in] sema A semaphore.

Returns: the current value of the semaphore

Definition at line 111 of file sema.h.

◆ sema_post()

int sema_post ( sema_t * sema )

Signal semaphore.

Precondition: (sema != NULL)

Parameters

[in] sema A semaphore.

Returns: 0, on success; -EOVERFLOW, if the semaphore's value would overflow.

◆ sema_try_wait()

static int sema_try_wait ( sema_t * sema )

inlinestatic

Test if the semaphore is posted.

Precondition: (sema != NULL)

This is a non-blocking alternative to sema_wait.

Returns: 0 on success; -EAGAIN, if the semaphore is not posted.; -ECANCELED, if the semaphore was destroyed.

Definition at line 188 of file sema.h.

◆ sema_wait()

static int sema_wait ( sema_t * sema )

inlinestatic

Wait for a semaphore being posted (without timeout).

Precondition: (sema != NULL)

Parameters

[in] sema A semaphore.

Returns: 0 on success; -ECANCELED, if the semaphore was destroyed.

Definition at line 172 of file sema.h.

◆ sema_wait_timed()

static int sema_wait_timed	(	sema_t *	sema,
		uint64_t	timeout
	)

inlinestatic

Wait for a semaphore being posted with a 64bit timeout.

Deprecated:: Will be removed after release 2021.07

Precondition: (sema != NULL)

Parameters

[in]	sema	A semaphore.
[in]	timeout	Time in microseconds until the semaphore times out. 0 does not wait.

Returns: 0 on success; -ETIMEDOUT, if the semaphore times out.; -ECANCELED, if the semaphore was destroyed.; -EAGAIN, if the semaphore is not posted (only if timeout = 0)

Definition at line 210 of file sema.h.

◆ sema_wait_timed_ztimer()

static int sema_wait_timed_ztimer	(	sema_t *	sema,
		ztimer_clock_t *	clock,
		uint32_t	timeout
	)

inlinestatic

Wait for a semaphore being posted, using ztimer as backend.

Precondition: (sema != NULL); (clock != NULL)

Parameters

[in]	sema	A semaphore.
[in]	clock	ztimer clock to use
[in]	timeout	Time in microseconds until the semaphore times out. 0 does not wait.

Returns: 0 on success; -ETIMEDOUT, if the semaphore times out.; -ECANCELED, if the semaphore was destroyed.; -EAGAIN, if the semaphore is not posted (only if timeout = 0)

Definition at line 232 of file sema.h.

Detailed Description

Modules

Files

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

◆ SEMA_CREATE

◆ SEMA_CREATE_LOCKED

Function Documentation

◆ _sema_wait_ztimer()

◆ sema_create()

◆ sema_destroy()

◆ sema_get_value()

◆ sema_post()

◆ sema_try_wait()

◆ sema_wait()

◆ sema_wait_timed()

◆ sema_wait_timed_ztimer()