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.

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 (semaphore_t *sm) __nonnull_all
	Wait on a semaphore.
int	sem_wait_timed (semaphore_t *sm, int timeout) __nonnull_all
	Wait on a semaphore (with a timeout).
int	sem_trywait (semaphore_t *sm) __nonnull_all
	"Wait" on a semaphore without blocking.
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.

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)

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)

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:

EINVAL - the semaphore was not initialized

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

sem_wait()

int sem_wait

(

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 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:

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

sem_wait_timed()

int sem_wait_timed	(	semaphore_t *	sm,
		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
EINVAL - the semaphore was not initialized
EINVAL - the timeout value was invalid (less than 0)
ETIMEDOUT - timed out while blocking