rmutex(3synch) rmutex(3synch)
NAME
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);
Parameters
rmutex pointer to rmutex to be initialized, locked, unlocked,
or destroyed
type USYNC_THREAD or USYNC_PROCESS
arg NULL (reserved for future use)
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 may 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 may lock it again while
the rmutex is locked; other threads are denied access as with
ordinary mutexes. Each rmutex_lock or rmutex_trylock 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.
Copyright 1994 Novell, Inc. Page 1
rmutex(3synch) rmutex(3synch)
rmutex_init
rmutex_init initializes an rmutex to be of type type and in
the unlocked state.
rmutex_lock
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. SS
"rmutex_trylock" 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
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.
Copyright 1994 Novell, Inc. Page 2
rmutex(3synch) rmutex(3synch)
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),
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(2)],
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.
USAGE
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(2), mutex(3synch), rmutex_init(3synch),
rmutex_destroy(3synch), rmutex_lock(3synch),
rmutex_trylock(3synch), rmutex_unlock(3synch), synch(3synch)
Copyright 1994 Novell, Inc. Page 3