Mutex Functions
[User API: Pico Layer]

Functions
POSEXTERN POSMUTEX_t	posMutexCreate (void)
POSEXTERN void	posMutexDestroy (POSMUTEX_t mutex)
POSEXTERN VAR_t	posMutexTryLock (POSMUTEX_t mutex)
POSEXTERN VAR_t	posMutexLock (POSMUTEX_t mutex)
POSEXTERN VAR_t	posMutexUnlock (POSMUTEX_t mutex)

---

Detailed Description

Mutexes are used for task synchronization. A source code area that is protected by a mutex can only be executed by one task at the time. The mechanism is comparable with a semaphore that is initialized with a counter of 1. A mutex is a special semaphore, that allows a task having the mutex locked can execute the mutex lock functions again and again without being blocked (this is called reentrancy).

---

Function Documentation

POSEXTERN POSMUTEX_t posMutexCreate (  void   )

Mutex function. Allocates a new mutex object. Returns: the pointer to the new mutex object. NULL is returned on error. Note: POSCFG_FEATURE_MUTEXES must be defined to 1 to have mutex support compiled in. See also: posMutexDestroy, posMutexLock, posMutexTryLock, posMutexUnlock

POSEXTERN void posMutexDestroy (  POSMUTEX_t  mutex  )

Mutex function. Frees a no more needed mutex object. Parameters: mutex  handle to the mutex object. Note: POSCFG_FEATURE_MUTEXES must be defined to 1 to have mutex support compiled in. POSCFG_FEATURE_MUTEXDESTROY must be defined to 1 to have this function compiled in. See also: posMutexCreate

POSEXTERN VAR_t posMutexLock (  POSMUTEX_t  mutex  )

Mutex function. This function locks a code section so that only one task can execute the code at a time. If an other task already has the lock, the task requesting the lock will be blocked until the mutex is unlocked again. Note that a posMutexLock appears always in a pair with posMutexUnlock. Parameters: mutex  handle to the mutex object. Returns: zero on success. Note: POSCFG_FEATURE_MUTEXES must be defined to 1 to have mutex support compiled in. See also: posMutexTryLock, posMutexUnlock, posMutexCreate

POSEXTERN VAR_t posMutexTryLock (  POSMUTEX_t  mutex  )

Mutex function. Tries to get the mutex lock. This function does not block when the mutex is not available, instead it returns a value showing that the mutex could not be locked. Parameters: mutex  handle to the mutex object. Returns: zero when the mutex lock could be set. Otherwise, when the mutex lock is yet helt by an other task, the function returns 1. A negative value is returned on error. Note: POSCFG_FEATURE_MUTEXES must be defined to 1 to have mutex support compiled in. POSCFG_FEATURE_MUTEXTRYLOCK must be defined to 1 to have this function compiled in. See also: posMutexLock, posMutexUnlock, posMutexCreate

POSEXTERN VAR_t posMutexUnlock (  POSMUTEX_t  mutex  )

Mutex function. This function unlocks a section of code so that other tasks are able to execute it. Parameters: mutex  handle to the mutex object. Returns: zero on success. Note: POSCFG_FEATURE_MUTEXES must be defined to 1 to have mutex support compiled in. See also: posMutexLock, posMutexTryLock, posMutexCreate

---