sem.h File Reference

Semaphores. More...

#include <kos/cdefs.h>

Go to the source code of this file.

Data Structures
struct	semaphore_t
	Semaphore type. More...

Macros
#define	SEM_INITIALIZER(value)
	Initializer for a transient semaphore.
#define	sem_wait_scoped(sm)
	Wait on a semaphore with scope management.

Functions
int	sem_init (semaphore_t *sm, int count)
	Initialize a semaphore for use.
int	sem_destroy (semaphore_t *sm) __nonnull_all
	Destroy a semaphore.
int	sem_wait_timed (semaphore_t *sm, unsigned int timeout) __nonnull_all
	Wait on a semaphore (with a timeout).
static __nonnull_all int	sem_wait (semaphore_t *sm)
	Wait on a semaphore.
int	sem_trywait (semaphore_t *sm) __nonnull_all
	"Wait" on a semaphore without blocking.
int	sem_wait_irqsafe (semaphore_t *sm) __nonnull_all
	Wait on a semaphore.
int	sem_signal (semaphore_t *sm) __nonnull_all
	Signal a semaphore.
int	sem_count (const semaphore_t *sm) __nonnull_all
	Retrieve the number of available resources.

Detailed Description

Semaphores.

This file defines semaphores. A semaphore is a synchronization primitive that allows a specified number of threads to be in its critical section at a single point of time. Another way to think of it is that you have a predetermined number of resources available, and the semaphore maintains the resources.

Author

Megan Potter

See also

kos/mutex.h

Macro Definition Documentation

SEM_INITIALIZER

#define SEM_INITIALIZER

(

value

)

Value:

{ 1, value }

Initializer for a transient semaphore.

Parameters

value

The initial count of the semaphore.

sem_wait_scoped

#define sem_wait_scoped

(

sm

)

Value:

__sem_wait_scoped((sm), __LINE__)

Wait on a semaphore with scope management.

This macro will wait on a semaphore, similarly to sem_wait, with the difference that the semaphore will automatically be signaled once the execution exits the functional block in which the macro was called.

Parameters

sm	The semaphore to wait on

Function Documentation

sem_count()

int sem_count

(

const semaphore_t *

sm

)

Retrieve the number of available resources.

This function will retrieve the count of available resources for a semaphore. This is not a thread-safe way to make sure resources will be available when you get around to waiting, so don't use it as such.

Parameters

sm	The semaphore to check

Returns

The count of the semaphore (the number of resources currently available)

References sem_signal().

sem_destroy()

int sem_destroy

(

semaphore_t *

sm

)

Destroy a semaphore.

This function destroys a semaphore, leaving it uninitialized. If there are any threads currently waiting on the semaphore, they will be woken with an ENOTRECOVERABLE error.

Parameters

sm	The semaphore to destroy

Return values

0	On success (no error conditions currently defined)

sem_init()

int sem_init	(	semaphore_t *	sm,
		int	count )

Initialize a semaphore for use.

This function initializes the semaphore passed in with the starting count value specified.

Parameters

sm	The semaphore to initialize
count	The initial count of the semaphore

Return values

0	On success
-1	On error, errno will be set as appropriate

Error Conditions:

EINVAL - the semaphore's value is invalid (less than 0)

Referenced by main().

sem_signal()

int sem_signal

(

semaphore_t *

sm

)

Signal a semaphore.

This function will release resources associated with a semaphore, signalling a waiting thread to continue on, if any are waiting. It is your responsibility to make sure you only release resources you have.

Parameters

sm	The semaphore to signal

Return values

0	On success
-1	On error, sets errno as appropriate

Error Conditions: None defined

Referenced by sem_count(), and thd_1().

sem_trywait()

int sem_trywait

(

semaphore_t *

sm

)

"Wait" on a semaphore without blocking.

This function will decrement the semaphore's count and return, if resources are available. Otherwise, it will return an error.

This function does not protect you against doing things that will cause a deadlock. This function, unlike the other waiting functions is safe to call inside an interrupt.

Parameters

sm	The semaphore to "wait" on

Return values

0	On success
-1	On error, sets errno as appropriate

Error Conditions:

EWOULDBLOCK - a call to sem_wait() would block

sem_wait()

static __nonnull_all int sem_wait ( semaphore_t * sm )

inlinestatic

Wait on a semaphore.

This function will decrement the semaphore's count and return, if resources are available. Otherwise, the function will block until the resources become available.

This function does not protect you against doing things that will cause a deadlock. This function is not safe to call in an interrupt. See sem_trywait() for a safe function to call in an interrupt.

Parameters

sm	The semaphore to wait on

Return values

0	On success
-1	On error, sets errno as appropriate

Error Conditions: None defined

References sem_wait_timed().

Referenced by thd_2().

sem_wait_irqsafe()

int sem_wait_irqsafe

(

semaphore_t *

sm

)

Wait on a semaphore.

This function will decrement the semaphore's count and return, if resources are available. Otherwise, the function will block until the resources become available.

This function can be used from within an interrupt context. In that case, if the semaphore is already used, an error will be returned.

Parameters

sm	The semaphore to wait on

Return values

0	On success
-1	On error, sets errno as appropriate

Error Conditions:

EWOULDBLOCK - the function was called inside an interrupt and the semaphore is not free

sem_wait_timed()

int sem_wait_timed	(	semaphore_t *	sm,
		unsigned int	timeout )

Wait on a semaphore (with a timeout).

This function will decrement the semaphore's count and return, if resources are available. Otherwise, the function will block until the resources become available or the timeout expires.

This function does not protect you against doing things that will cause a deadlock. This function is not safe to call in an interrupt. See sem_trywait() for a safe function to call in an interrupt.

Parameters

sm	The semaphore to wait on
timeout	The maximum number of milliseconds to block (a value of 0 here will block indefinitely)

Return values

0	On success
-1	On error, sets errno as appropriate

Error Conditions:

EPERM - called inside an interrupt
ETIMEDOUT - timed out while blocking

Referenced by sem_wait(), and thd_2().