rmutex(SYNCH)
rmutex: rmutex_init, rmutex_lock, rmutex_trylock, rmutex_unlock, rmutex_destroy --
overview of mutual exclusion lock routines
Synopsis
cc [options] -Kthread file
#include <synch.h>
int rmutex_init(rmutex_t *rmutex, int type, void *arg);
int rmutex_lock(rmutex_t *rmutex);
int rmutex_trylock(rmutex_t *rmutex);
int rmutex_unlock(rmutex_t *rmutex);
int rmutex_destroy(rmutex_t *rmutex);
Description
Mutual exclusion locks, or mutexes,
are used to serialize the execution of threads.
They are typically used to ensure
that only one thread at a time accesses shared data.
Recursive mutual exclusion locks, or rmutexes,
are mutexes that can be locked recursively.
That is, a thread that has locked an rmutex
can lock it again without releasing it;
the thread that has locked an rmutex is referred to as the owner of the rmutex.
Only the owner of an rmutex can lock it again while the rmutex is locked;
other threads are denied access as with ordinary mutexes.
Each rmutex_lock(SYNCH) or rmutex_trylock(SYNCH) call
must be matched by a corresponding rmutex_unlock
before the rmutex is made available to threads other than the owner.
Note that rmutexes, like mutexes, protect data only when the convention
of acquiring the rmutex is faithfully followed before any access
of the data.
The Threads Library provides five routines
to manipulate rmutexes;
these are outlined below
and described in more detail on individual manual pages.
Parameters
rmutex-
pointer to rmutex to be initialized, locked, unlocked, or destroyed
type-
USYNC_THREAD or USYNC_PROCESS
arg-
NULL (reserved for future use)
rmutex_init(3synch)
rmutex_init initializes an rmutex
to be of type type and in the unlocked state.
rmutex_lock(3synch)
rmutex_lock locks
the rmutex pointed to by rmutex.
If rmutex is locked by another thread,
the calling thread is blocked until rmutex becomes available.
When rmutex_lock returns successfully,
the caller has locked rmutex.
If rmutex is already locked by the calling thread,
the recursive depth is incremented
and control is returned to the caller,
as if the lock had just been acquired.
rmutex_trylock(3synch)
rmutex_trylock attempts once to acquire the
rmutex pointed to by rmutex.
If rmutex is available,
rmutex_trylock will return successfully
with rmutex locked.
If rmutex is already locked by another thread,
rmutex_trylock immediately returns EBUSY to the caller
without acquiring rmutex or blocking.
If rmutex is already held by the calling thread,
the recursive depth is incremented and control is returned
to the caller,
as if the lock had just been acquired.
rmutex_unlock(3synch)
rmutex_unlock unlocks the rmutex pointed to by rmutex.
rmutex_unlock checks the identity of the caller
and, if the caller is the current owner of rmutex,
it checks the depth count.
-
If the depth count is greater than 0,
it decrements the count and returns to the caller
without unlocking the rmutex.
-
If the depth count is 0, the rmutex is unlocked.
If the caller is not the current owner of rmutex,
that is, the caller does not hold the lock,
rmutex_unlock will fail and return EACCES.
If there are one or more threads waiting for rmutex
when it is unlocked,
at least one waiting thread is
allowed to try again to lock rmutex.
rmutex_destroy
rmutex_destroy destroys the rmutex pointed to by rmutex.
This includes invalidating rmutex and freeing any
associated implementation-allocated dynamic resources.
USYNC_THREAD and USYNC_PROCESS recursive mutexes
Recursive mutexes are initialized to be one of two types:
USYNC_THREAD or USYNC_PROCESS.
USYNC_THREAD rmutexes are available
only to threads within the current process.
USYNC_PROCESS rmutexes can be used by threads
in different processes.
General information
Recursive mutexes must be initialized
(see rmutex_init(SYNCH)),
before being passed to any of the other rmutex routines.
Locks acquired with rmutex_lock or rmutex_trylock
must be released with rmutex_unlock.
From the point of view of the caller,
rmutex_lock is atomic:
even if interrupted by a signal or forkall (see
fork(S)),
rmutex_lock will not return until it holds
the locked rmutex.
As a consequence, if rmutex_lock is interrupted,
an error indication such as EINTR is never returned to the caller.
Warnings
If a thread exits while holding an rmutex,
the rmutex will not be unlocked,
and other threads waiting for the rmutex will wait forever.
Similarly, if a process exits while holding a USYNC_PROCESS rmutex,
the rmutex will not be unlocked,
and other processes or threads waiting for the rmutex will wait forever.
References
fork(S),
Intro(SYNCH),
mutex(SYNCH),
rmutex_init(SYNCH),
rmutex_destroy(SYNCH),
rmutex_lock(SYNCH),
rmutex_trylock(SYNCH),
rmutex_unlock(SYNCH)
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 - 01 June 2005