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)   { 1, value }
	Initializer for a transient semaphore.

Functions
semaphore_t *	sem_create (int value) __depr("Use sem_init or SEM_INITIALIZER.")
	Allocate a new semaphore.
int	sem_init (semaphore_t *sm, int count)
	Initialize a semaphore for use.
int	sem_destroy (semaphore_t *sem)
	Destroy a semaphore.
int	sem_wait (semaphore_t *sem)
	Wait on a semaphore.
int	sem_wait_timed (semaphore_t *sem, int timeout)
	Wait on a semaphore (with a timeout).
int	sem_trywait (semaphore_t *sem)
	"Wait" on a semaphore without blocking.
int	sem_signal (semaphore_t *sem)
	Signal a semaphore.
int	sem_count (semaphore_t *sem)
	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

)

{ 1, value }

Initializer for a transient semaphore.

Parameters

value

The initial count of the semaphore.

Function Documentation

sem_count()

int sem_count

(

semaphore_t *

sem

)

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

sem	The semaphore to check

Returns

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

sem_create()

semaphore_t * sem_create

(

int

value

)

Allocate a new semaphore.

This function allocates and initializes a new semaphore for use.

Deprecated

This function is formally deprecated. Please update your code to use sem_init() or static initialization with SEM_INITIALIZER instead.

Parameters

value

The initial count of the semaphore (the number of threads to allow in the critical section at a time)

Returns

The created semaphore on success. NULL is returned on failure and errno is set as appropriate.

Error Conditions:

ENOMEM - out of memory
EINVAL - the semaphore's value is invalid (less than 0)

sem_destroy()

int sem_destroy

(

semaphore_t *

sem

)

Destroy a semaphore.

This function frees a semaphore, releasing any memory associated with it. If there are any threads currently waiting on the semaphore, they will be woken with an ENOTRECOVERABLE error.

Parameters

sem	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)

sem_signal()

int sem_signal

(

semaphore_t *

sem

)

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

sem	The semaphore to signal

Return values

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

Error Conditions:

EINVAL - the semaphore was not initialized

sem_trywait()

int sem_trywait

(

semaphore_t *

sem

)

"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

sem	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
EINVAL - the semaphore was not initialized

sem_wait()

int sem_wait

(

semaphore_t *

sem

)

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

sem	The semaphore to wait on

Return values

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

Error Conditions:

EPERM - called inside an interrupt
EINVAL - the semaphore was not initialized

sem_wait_timed()

int sem_wait_timed	(	semaphore_t *	sem,
		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

sem	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
EINVAL - the semaphore was not initialized
EINVAL - the timeout value was invalid (less than 0)
ETIMEDOUT - timed out while blocking