Semaphores

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.
#define	SEMA_CREATE_LOCKED()   { (0), SEMA_OK, MUTEX_INIT_LOCKED }
	Creates semaphore statically initialized to 0.

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

Functions
void	sema_create (sema_t *sema, unsigned int value)
	Creates semaphore dynamically.
void	sema_destroy (sema_t *sema)
	Destroys a semaphore.
static unsigned	sema_get_value (const sema_t *sema)
	Get a semaphore's current value.
int	_sema_wait_ztimer (sema_t *sema, int block, ztimer_clock_t *clock, uint32_t timeout)
	Wait for a semaphore, blocking or non-blocking.
static int	sema_wait (sema_t *sema)
	Wait for a semaphore being posted (without timeout).
static int	sema_try_wait (sema_t *sema)
	Test if the semaphore is posted.
static int	sema_wait_timed (sema_t *sema, uint64_t timeout)
	Wait for a semaphore being posted with a 64bit timeout.
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.
int	sema_post (sema_t *sema)
	Signal semaphore.

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 49 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 55 of file sema.h.

Enumeration Type Documentation

sema_state_t

enum sema_state_t

A Semaphore states.

Definition at line 60 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 112 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 189 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 173 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 211 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 233 of file sema.h.