2.5.1 Semaphore¶
-
typedef struct ZixSemImpl ZixSem¶
A counting semaphore.
This is an integer that is never negative, and has two main operations: increment (post) and decrement (wait). If a decrement can’t be performed (because the value is 0) the caller will be blocked until another thread posts and the operation can succeed.
Semaphores can be created with any starting value, but typically this will be 0 so the semaphore can be used as a simple signal where each post corresponds to one wait.
Semaphores are very efficient (much moreso than a mutex/cond pair). In particular, at least on Linux, post is async-signal-safe, which means it does not block and will not be interrupted. If you need to signal from a realtime thread, this is the most appropriate primitive to use.
-
ZixStatus zix_sem_destroy(ZixSem *sem)¶
Destroy
sem.- Returns:
ZixStatus.ZIX_STATUS_SUCCESS, or an error.
-
ZixStatus zix_sem_init(ZixSem *sem, unsigned initial)¶
Create
semwith the giveninitialvalue.- Returns:
ZixStatus.ZIX_STATUS_SUCCESS, or an unlikely error.
-
ZixStatus zix_sem_post(ZixSem *sem)¶
Increment and signal any waiters.
Realtime safe.
- Returns:
ZixStatus.ZIX_STATUS_SUCCESSifsemwas incremented,ZixStatus.ZIX_STATUS_OVERFLOWif the maximum possible value would have been exceeded, orZixStatus.ZIX_STATUS_BAD_ARGifsemis invalid.
-
ZixStatus zix_sem_timed_wait(ZixSem *sem, uint32_t seconds, uint32_t nanoseconds)¶
Wait for an amount of time until count is > 0, then decrement if possible.
Obviously not realtime safe.
- Returns:
ZixStatus.ZIX_STATUS_SUCCESSifsemwas decremented,ZixStatus.ZIX_STATUS_TIMEOUTif it was still zero when the timeout was reached,ZixStatus.ZIX_STATUS_NOT_SUPPORTEDif the system does not support timed waits, orZixStatus.ZIX_STATUS_BAD_ARGifsemis invalid.
-
ZixStatus zix_sem_try_wait(ZixSem *sem)¶
Non-blocking version of wait().
- Returns:
ZixStatus.ZIX_STATUS_SUCCESSifsemwas decremented,ZixStatus.ZIX_STATUS_UNAVAILABLEif it was already zero, orZixStatus.ZIX_STATUS_BAD_ARGifsemis invalid.
-
ZixStatus zix_sem_wait(ZixSem *sem)¶
Wait until count is > 0, then decrement.
Obviously not realtime safe.
- Returns:
ZixStatus.ZIX_STATUS_SUCCESSifsemwas decremented, orZixStatus.ZIX_STATUS_BAD_ARGifsemis invalid.