- Main Page
- Modules
- Data Structures
- Files

# Semaphore Functions
[User API: Pico Layer]

## Functions
POSEXTERN POSSEMA_t | posSemaCreate (INT_t initcount)
POSEXTERN void | posSemaDestroy (POSSEMA_t sema)
POSEXTERN VAR_t | posSemaGet (POSSEMA_t sema)
POSEXTERN VAR_t | posSemaSignal (POSSEMA_t sema)
POSEXTERN VAR_t | posSemaWait (POSSEMA_t sema, UINT_t timeoutticks)

## Detailed Description

Semaphores are basically used for task synchronization. Task synchronization means that only a defined number of tasks can execute a piece of code. Usually, a semaphore is initialized with the value 1, so only one task can hold the semaphore at a time (Please read the chapter about the mutex functions also if you are interested in task synchronization).
The second thing semaphores can be used for is sending signals to waiting tasks. Imagine you have an interrupt service routine that is triggered every time when a big chunk of data is available on a device. The data is to big to process them directly in the ISR. The ISR will only trigger a semaphore (it will signalize the semaphore), and a high priorized task waiting for the semaphore will be set to running state and will process the data from the device. In this case, the semaphore would be initialized with zero when it is created. The first task requesting the semaphore would block immediately, and can only proceed its work when the semaphore is triggered from outside.

Semaphores are implemented as counters. A task requesting a semaphore (via posSemaGet or posSemaWait) will decrement the counter. If the counter is zero, the task willing to decrement the counter is blocked. When a semaphore is signaled (via posSemaSignal), the counter is incremented. If the counter reaches a positive, nonzero value, the highest priorized task pending on the semaphore is set to running state and can decrement the counter by itself.

## Function Documentation

POSEXTERN POSSEMA_t posSemaCreate | ( | INT_t | initcount | ) |

  | Semaphore function. Allocates a new semaphore object. Parameters:
  | initcount | Initial semaphore count (see detailed semaphore description).
Returns: the pointer to the new semaphore object. NULL is returned on error. Note: POSCFG_FEATURE_SEMAPHORES must be defined to 1 to have semaphore support compiled in. See also: posSemaDestroy, posSemaGet, posSemaWait, posSemaSignal

POSEXTERN void posSemaDestroy | ( | POSSEMA_t | sema | ) |

  | Semaphore function. Frees a no more needed semaphore object. Parameters:
  | sema | handle to the semaphore object.
Note: POSCFG_FEATURE_SEMAPHORES must be defined to 1 to have semaphore support compiled in. POSCFG_FEATURE_SEMADESTROY must be defined to 1 to have this function compiled in. See also: posSemaCreate

POSEXTERN VAR_t posSemaGet | ( | POSSEMA_t | sema | ) |

  | Semaphore function. This function tries to get the semaphore object. If the semaphore is in nonsignalized state (that means its counter is zero or less), this function blocks the task execution until the semaphore gets signaled. Parameters:
  | sema | handle to the semaphore object.
Returns: zero on success. Note: POSCFG_FEATURE_SEMAPHORES must be defined to 1 to have semaphore support compiled in. See also: posSemaWait, posSemaSignal, posSemaCreate

POSEXTERN VAR_t posSemaSignal | ( | POSSEMA_t | sema | ) |

  | Semaphore function. This function signalizes a semaphore object, that means it increments the semaphore counter and sets tasks pending on the semaphore to running state, when the counter reaches a positive, nonzero value. Parameters:
  | sema | handle to the semaphore object.
Returns: zero on success. Note: POSCFG_FEATURE_SEMAPHORES must be defined to 1 to have semaphore support compiled in. See also: posSemaGet, posSemaWait, posSemaCreate

POSEXTERN VAR_t posSemaWait | ( | POSSEMA_t | sema,
|  | UINT_t | timeoutticks
| ) |

  | Semaphore function. This function tries to get the semaphore object. If the semaphore is in nonsignalized state (that means its counter is zero or less), this function blocks the task execution until the semaphore gets signaled or a timeout happens. Parameters:
  | sema | handle to the semaphore object.
  | timeoutticks | timeout in timer ticks (see HZ define and MS macro). If this parameter is set to zero, the function immediately returns. If this parameter is set to INFINITE, the function will never time out.
Returns: zero on success. A positive value (1 or TRUE) is returned when the timeout was reached. Note: POSCFG_FEATURE_SEMAPHORES must be defined to 1 to have semaphore support compiled in. POSCFG_FEATURE_SEMAWAIT must be defined to 1 to have this function compiled in. See also: posSemaGet, posSemaSignal, posSemaCreate, HZ, MS