sem.h File Reference

Semaphores. More...

#include <sys/cdefs.h>

Go to the source code of this file.

Data Structures
struct	semaphore
	Semaphore type. More...

Macros
#define	SEM_INITIALIZER(value)   { 1, value }
	Initializer for a transient semaphore. More...

Typedefs
typedef struct semaphore	semaphore_t
	Semaphore type. More...

Functions
semaphore_t *	sem_create (int value) __attribute__((deprecated))
	Allocate a new semaphore. More...
int	sem_init (semaphore_t *sm, int count)
	Initialize a semaphore for use. More...
int	sem_destroy (semaphore_t *sem)
	Destroy a semaphore. More...
int	sem_wait (semaphore_t *sem)
	Wait on a semaphore. More...
int	sem_wait_timed (semaphore_t *sem, int timeout)
	Wait on a semaphore (with a timeout). More...
int	sem_trywait (semaphore_t *sem)
	"Wait" on a semaphore without blocking. More...
int	sem_signal (semaphore_t *sem)
	Signal a semaphore. More...
int	sem_count (semaphore_t *sem)
	Retrieve the number of available resources. More...

Detailed Description

Semaphores.

This file defines semaphores. A semaphore is a synchronization primitive that allows a spcified 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

Dan Potter

See also

kos/mutex.h

Macro Definition Documentation

#define SEM_INITIALIZER

(

value

)

{ 1, value }

Initializer for a transient semaphore.

Parameters

value

The initial count of the semaphore.

Typedef Documentation

typedef struct semaphore semaphore_t

Semaphore type.

This structure defines a semaphore. There are no public members of this structure for you to actually do anything with in your code, so don't try.

Function Documentation

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)

semaphore_t* sem_create

(

int

value

)

Allocate a new semaphore.

This function allocates and initializes a new semaphore for use.

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)

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)

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)

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

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

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

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