Semaphores

Lightweight semaphore implementation. More...

Detailed Description

Lightweight semaphore implementation.

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...
int	_sema_wait (sema_t *sema, int block, uint64_t timeout)
	Wait for a semaphore, blocking or non-blocking. More...
static int	sema_wait_timed (sema_t *sema, uint64_t timeout)
	Wait for a semaphore being posted. 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...
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 44 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 50 of file sema.h.

Function Documentation

_sema_wait()

int _sema_wait	(	sema_t *	sema,
		int	block,
		uint64_t	timeout
	)

Wait for a semaphore, blocking or non-blocking.

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

Precondition

(sema != NULL)

Parameters

[in]	sema	A semaphore.
[in]	block	if true, block until semaphore is available.
[in]	timeout	if blocking, time in microseconds 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_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 165 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 149 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.

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