ABILOCK(3X)ABILOCK(3X)NAME
init_lock, acquire_lock, release_lock, stat_lock, spin_lock - ABI mutual
exclusion primitives
SYNOPSIS
#include <abi_mutex.h>
int init_lock(abilock_t *lck);
int acquire_lock(abilock_t *lck);
int release_lock(abilock_t *lck);
int stat_lock(abilock_t *lck);
void spin_lock(abilock_t *lck);
DESCRIPTION
These routines provide a simple, standard interface to base level mutual
exclusion primitives. They are found in the library ``libmutex.so'', and
is loaded if the option ``-lmutex'' is used with cc(1) or ld(1).
The parameter lck must point to memory shared by all processes wishing to
acquire or test the lock.
The contents of the structure abilock_t are as follows:
typedef struct {
unsigned int abi_lock;
} abilock_t;
The function init_lock must be called on a lock before any of the other
functions. It initializes the lock to an unlocked state. A non-zero
return status will indicate an error.
acquire_lock tries once to acquire the lock referenced by lck. It
returns zero if the lock was acquired, otherwise non-zero. acquire_lock
can always fail, even if it is known that the lock is free and there is
only one process, this implies that acquire_lock should always be called
in a loop.
spin_lock will always acquire the lock. If the lock is not immediately
available, the calling process will either spin (busy-wait) or be
suspended until the lock becomes available. There is no implied policy
as to which (if there is more than one) waiting process will be granted
the lock.
stat_lock returns the current state of the lock referenced by lck without
attempting to acquire the lock. It returns UNLOCKED if the lock is free,
otherwise LOCKED.
Page 1
ABILOCK(3X)ABILOCK(3X)
release_lock unconditionally releases the lock pointed to by lck. The
ability for one process to release the lock of another process is
permitted. A non-zero return status will indicate an error.
These routines will work for locks shared between 32-bit and 64-bit user
programs.
SEE ALSOnanosleep(2), sginap(2), usinit(3P).
DIAGNOSTICS
init_lock, acquire_lock, and release_lock return 0 if the operation was a
success, otherwise a non-zero value. spin_lock returns no value.
WARNINGS
No locks are ever freed automatically by the system. Locks acquired by a
process that terminates remain locked.
Since looping is necessary when attempting to acquire a lock using
acquire_lock, the user process could find itself in a long busy-wait
loop. To avoid wasting CPU cycles, programs should implement some kind
of back-off strategy, perhaps calling sginap(2) or nanosleep(2) after
some number of unsuccessful calls to acquire_lock.
Even though stat_lock returns status indicating that the lock is
available, a call to acquire_lock could still fail.
Page 2
