KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Data Structures | Macros | Typedefs | Functions
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_tsem_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
valueThe 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
semThe 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
valueThe 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
semThe semaphore to destroy
Return values
0On 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
smThe semaphore to initialize
countThe initial count of the semaphore
Return values
0On success
-1On 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
semThe semaphore to signal
Return values
0On success
-1On 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
semThe semaphore to "wait" on
Return values
0On success
-1On 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
semThe semaphore to wait on
Return values
0On success
-1On 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
semThe semaphore to wait on
timeoutThe maximum number of milliseconds to block (a value of 0 here will block indefinitely)
Return values
0On success
-1On 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