brickOS Kernel Developer v0.9.0
semaphore.h File Reference

Interface: POSIX 1003.1b semaphores for task synchronization. More...

#include <config.h>
#include <time.h>
#include <atomic.h>
Include dependency graph for semaphore.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define EAGAIN   0xffff
 the error code
 

Typedefs

typedef atomic_t sem_t
 the semaphore data-type
 

Functions

int sem_init (sem_t *sem, int pshared, unsigned int value)
 Initialize a semaphore.
 
int sem_wait (sem_t *sem)
 Wait for semaphore (blocking)
 
int sem_timedwait (sem_t *sem, const time_t abs_timeout)
 Wait for semaphore (blocking with timeout).
 
int sem_trywait (sem_t *sem)
 Try a wait for semaphore (non-blocking)
 
int sem_post (sem_t *sem)
 Post a semaphore.
 
int sem_getvalue (sem_t *sem, int *sval)
 Get the semaphore value.
 
int sem_destroy (sem_t *sem)
 We're done with the semaphore, destroy it.
 

Detailed Description

Interface: POSIX 1003.1b semaphores for task synchronization.

Author
Markus L. Noga marku.nosp@m.s@no.nosp@m.ga.de

Definition in file semaphore.h.

Macro Definition Documentation

◆ EAGAIN

#define EAGAIN   0xffff

the error code

Definition at line 48 of file semaphore.h.

Typedef Documentation

◆ sem_t

typedef atomic_t sem_t

the semaphore data-type

Definition at line 46 of file semaphore.h.

Function Documentation

◆ sem_destroy()

int sem_destroy ( sem_t sem)
externinline

We're done with the semaphore, destroy it.

sem_destroy() destroys a semaphore object, freeing the resources it might hold.

Parameters
sema pointer to the semaphore to be destroyed
Returns
(always returns 0)

NOTE: No tasks should be waiting on the semaphore at the time sem_destroy is called.

Definition at line 147 of file semaphore.h.

◆ sem_getvalue()

int sem_getvalue ( sem_t sem,
int *  sval 
)
externinline

Get the semaphore value.

Definition at line 132 of file semaphore.h.

◆ sem_init()

int sem_init ( sem_t sem,
int  pshared,
unsigned int  value 
)
externinline

Initialize a semaphore.

sem_init() initializes the semaphore object pointed to by {sem} by setting its internal count to {value}

Parameters
sema pointer to the semaphore to be initialized
valuethe initial value for count
pshared(this argument is ignored)
Returns
(always 0)

Definition at line 64 of file semaphore.h.

◆ sem_post()

int sem_post ( sem_t sem)
externinline

Post a semaphore.

sem_post() atomically increases the count of the semaphore pointed to by {sem}. This function never blocks and can safely be used in asynchronous signal handlers.

Parameters
sema pointer to the semaphore to be signaled
Returns
(always returns 0)

Definition at line 123 of file semaphore.h.

References atomic_inc().

◆ sem_timedwait()

int sem_timedwait ( sem_t sem,
const time_t  abs_timeout 
)
extern

Wait for semaphore (blocking with timeout).

sem_timedwait() suspends the calleing task until either the semaphore pointed to by {sem} has non-zero count or the given absolute timeout passed. Note the timeout is an ABSOLUTE time not relative (yes the standard is that stupid); so if you want a relative waiting time, call the function with get_system_up_time() + relativeTime.

If the semaphore reached a non-zero count its value is then atomically decreased.

Parameters
sema pointer to the semaphore on which to wait
abs_timeoutthe absolute timeout of this operation. If the semaphore cannot be locked up to this time, this function returns.
Returns
0 if the semaphore could successfully be locked; -1 if the timeout has been reached.
Note
in IEEE 1003.1, the timeout is passed as a struct timeval not a time_t.

◆ sem_trywait()

int sem_trywait ( sem_t sem)
extern

Try a wait for semaphore (non-blocking)

sem_trywait() is a non-blocking variant of sem_wait(). If the semaphore pointed to by {sem} has non-zero count, the count is atomically decreased and sem_trywait immediately returns 0. If the semaphore count is zero, sem_trywait immediately returns with error EAGAIN.

Parameters
sema pointer to the semaphore on which to attempt a wait
Returns
0 if decremented the semaphore or EAGAIN if can't

NOTE: this is IRQ handler safe.

◆ sem_wait()

int sem_wait ( sem_t sem)
extern

Wait for semaphore (blocking)

sem_wait() suspends the calling task until the semaphore pointed to by {sem} has non-zero count. It then atomically decreases the semaphore count.

Parameters
sema pointer to the semaphore on which to wait
Returns
0 if wait returned immediately, EAGAIN if task did have to wait for the semaphore.