MTX(3C) | Standard C Library Functions | MTX(3C) |
mtx
, mtx_destroy
,
mtx_init
, mtx_lock
,
mtx_timedlock
, mtx_trylock
,
mtx_unlock
— C11 mutex
operations
#include
<threads.h>
int
mtx_init
(mtx_t *mtx,
int type);
void
mtx_destroy
(mtx_t *mtx);
int
mtx_lock
(mtx_t *mtx);
int
mtx_timedlock
(mtx_t *mtx,
const struct timespec *restrict ts);
int
mtx_trylock
(mtx_t *mtx);
int
mtx_unlock
(mtx_t *mtx);
The mtx family of functions implement mutual exclusion locks (mutexes) and behave similarly to both POSIX threads and illumos threads; however, they have slightly different call signatures and return values. For more information, see threads(7). Importantly, they do not allow for inter-process synchronization.
The
mtx_init
()
function initializes the mutex specified by mtx. The
following types of mutexes are valid and may be specified by the
type argument:
mtx_plain
mtx_timed
mtx_plain
|
mtx_recursive
mtx_timed
|
mtx_recursive
The
mtx_destroy
()
function destroys the mutex pointed to by mtx. It is
illegal for threads to be blocked waiting for mtx when
mtx_destroy
() is called .
The mtx_lock
() function attempts to lock
the mutex mtx. When the function returns, it will be
the sole owner of the mutex and must call
mtx_unlock
() when it is done, or risk inducing a
deadlock in the process. Other threads that make calls to
mtx_lock
() after another thread has successfully
completed its call to mtx_lock
() will block. When
they finally return, then they will have obtained the mutex
mtx.
Unless a lock of type
mtx_recursive
was created, a thread calling
mtx_lock
()
when it already holds mtx will cause the thread to
deadlock. Otherwise, the lock will be successfully taken again. However, a
thread must call mtx_unlock
() for each time that it
has acquired mtx.
The
mtx_trylock
()
function will attempt to obtain the mutex pointed to by
mtx. However, unlike
mtx_lock
(), if mtx is locked,
then it will not block and wait for mtx and instead
return thrd_busy
to indicate that the lock is
currently held.
The
mtx_timedlock
()
function attempts to obtain the mutex pointed to by
mtx. If it is unable to obtain it, then it will block
for a set amount of time dictated by ts. The timeout
in ts is treated as an absolute time in UTC to block
until, measured based on the CLOCK_REALTIME
clock.
The
mtx_unlock
()
function unlocks the mutex pointed to by mtx, which
allows another thread the opportunity to obtain it. If any threads are
actively blocking on the mutex, one of them will obtain it and be woken up.
It is an error to call mtx_unlock
() on a mutex which
the calling thread does not currently own.
Upon successful completion, the function
mtx_init
() returns
thrd_success
. If there was insufficient memory to
create the thread, it instead returns thrd_nomem
. If
any other error occurred, it returns thrd_error
.
The functions mtx_lock
(), and
mtx_unlock
() return
thrd_success
. If they were unable to successfully
complete the operation, they instead return
thrd_error
.
Upon successful completion, the
mtx_timedlock
() function returns
thrd_success
. If the timeout is reached and the
calling thread is unable to obtain the mutex, then
thrd_timedout
is returned. If any other error
occurs, then thrd_error
is returned.
Upon successful completion, the
mtx_trylock
() function returns
thrd_success
. If the thread was unable to obtain the
mutex because another thread owns it, then it returns
thrd_busy
. Otherwise, an error will have occurred
and thrd_error
is returned.
mutex_init(3C), pthread_mutex_destroy(3C), pthread_mutex_init(3C), pthread_mutex_lock(3C), pthread_mutex_timedlock(3C), pthread_mutex_trylock(3C), pthread_mutex_unlock(3C), threads.h(3HEAD), attributes(7)
February 14, 2020 | OmniOS |