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_init(ZixSem *sem, unsigned initial)¶
Create
sem
with the giveninitial
value.- Returns:
ZixStatus.ZIX_STATUS_SUCCESS
, or an unlikely error.
-
ZixStatus zix_sem_destroy(ZixSem *sem)¶
Destroy
sem
.- Returns:
ZixStatus.ZIX_STATUS_SUCCESS
, or an error.
-
ZixStatus zix_sem_post(ZixSem *sem)¶
Increment and signal any waiters.
Realtime safe.
- Returns:
ZixStatus.ZIX_STATUS_SUCCESS
ifsem
was incremented,ZixStatus.ZIX_STATUS_OVERFLOW
if the maximum possible value would have been exceeded, orZixStatus.ZIX_STATUS_BAD_ARG
ifsem
is invalid.
-
ZixStatus zix_sem_wait(ZixSem *sem)¶
Wait until count is > 0, then decrement.
Obviously not realtime safe.
- Returns:
ZixStatus.ZIX_STATUS_SUCCESS
ifsem
was decremented, orZixStatus.ZIX_STATUS_BAD_ARG
ifsem
is invalid.
-
ZixStatus zix_sem_try_wait(ZixSem *sem)¶
Non-blocking version of wait().
- Returns:
ZixStatus.ZIX_STATUS_SUCCESS
ifsem
was decremented,ZixStatus.ZIX_STATUS_UNAVAILABLE
if it was already zero, orZixStatus.ZIX_STATUS_BAD_ARG
ifsem
is 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_SUCCESS
ifsem
was decremented,ZixStatus.ZIX_STATUS_TIMEOUT
if it was still zero when the timeout was reached,ZixStatus.ZIX_STATUS_NOT_SUPPORTED
if the system does not support timed waits, orZixStatus.ZIX_STATUS_BAD_ARG
ifsem
is invalid.