Semaphores

Functions

void sem_init (sem_t *sem, int count)
 
void sem_deinit (sem_t *sem)
 
sem_t * sem_create (int count)
 
void sem_destroy (sem_t *sem)
 
void sem_signal (sem_t *sem)
 
void sem_wait (sem_t *sem)
 
int sem_wait_tmo (sem_t *sem, tick_t time)
 
void sem_set_name (sem_t *sem, const char *name)
 
void sem_show (void)
 
void sem_show_with_fmt_fn (fmt_fn_t fn)
 

Detailed Description

Function Documentation

◆ sem_create()

sem_t* sem_create ( int  count)

Allocates and initialises a semaphore handle. See sem_init() for further details.

Parameters
countInitial count
Returns
The semaphore handle to be used in all subsequent operations on the semaphore.

◆ sem_deinit()

void sem_deinit ( sem_t *  sem)

Deinitialises a semaphore handle. The semaphore must not be in use when this function is called (no task can be waiting for the semaphore, nor can they do so at any time after calling this function).

This function must not be called with a handle that was returned by sem_create(). See sem_destroy().

Parameters
semSemaphore handle

◆ sem_destroy()

void sem_destroy ( sem_t *  sem)

Frees the resources allocated by the semaphore. The semaphore must not be in use when this function is called (no task can be waiting for the semaphore, nor can they do so at any time after calling this function).

This function must only be called with a handle that was returned by sem_create().

Parameters
semSemaphore handle

◆ sem_init()

void sem_init ( sem_t *  sem,
int  count 
)

Initialises a semaphore handle. The count argument determines how many times the semaphore can be taken before the calling task is put in the WAITING state.

A semaphore used for synchronisation between two tasks should be initialised to 0. The task trying to take the semaphore will be blocked until the other task calls sem_signal(). This is the primary use case for semaphores.

A semaphore being used to guard shared resources should be initialised with the number of available resources. When the semaphore has been taken count times, the next task trying to take the semaphore will be blocked. Note that a semaphore alone is usually not sufficient for properly guarding the resources.

Semaphores should not be used for mutual exclusion. Mutexes are optimised for this type of operation and should be used instead.

This function must not be called with a handle that was returned by sem_create().

Parameters
semSemaphore handle
countInitial count

◆ sem_set_name()

void sem_set_name ( sem_t *  sem,
const char *  name 
)

Sets the name of the semaphore.

This function is only used for debugging purposes, where a kernel-aware debugger may present this name to the user.

The name will be stored in a separate table for kernel objects. If the name could not be set, the error is silently ignored.

Parameters
semSemaphore handle
nameString describing semaphore

◆ sem_show()

void sem_show ( void  )

Prints all registered semaphores to stdout using rprintp(). This may prove useful for debugging purposes. This function should not be called from application code, but may be called from e.g. uerror() or an exception handler.

◆ sem_show_with_fmt_fn()

void sem_show_with_fmt_fn ( fmt_fn_t  fn)

Same as sem_show(), but using supplied function for formatted output.

Parameters
fnFunction for formatted output

◆ sem_signal()

void sem_signal ( sem_t *  sem)

Signals the semaphore. The first task that was waiting on the semaphore (if any) will be put in the READY state.

Parameters
semSemaphore handle

◆ sem_wait()

void sem_wait ( sem_t *  sem)

Waits for the semaphore. If the semaphore is available, the function will return immediately. If the semaphore is not available, the calling task will be put in the WAITING state until another task calls sem_signal() on the semaphore.

Parameters
semSemaphore handle

◆ sem_wait_tmo()

int sem_wait_tmo ( sem_t *  sem,
tick_t  time 
)

Analogous to sem_wait(), but a maximum time to wait can be specified. If the semaphore is not available, the calling task will wait until the semaphore becomes available, or the number of ticks given by time expires.

Parameters
semSemaphore handle
timeNumber of ticks to wait
Returns
0 if the semaphore was acquired successfully, 1 if the service timed out.