USSETLOCK(3P)USSETLOCK(3P)NAME
ussetlock, uscsetlock, uswsetlock, ustestlock, usunsetlock - spinlock
routines
FORTRAN SYNOPSIS
integer*4 function ussetlock (lock)
TYPE lock
integer*4 function uscsetlock (lock, spins)
TYPE lock
integer*4 spins
integer*4 function uswsetlock (lock, spins)
TYPE lock
integer*4 spins
integer*4 function ustestlock (lock)
TYPE lock
integer*4 function usunsetlock (lock)
TYPE lock
where TYPE is integer*4 in 32 bit mode, and is integer*8 in 64
bit mode.
DESCRIPTION
This set of routines provide a standard test and set facility. If the
lock is free then it is atomically locked, and control is returned to the
caller. If the lock is already locked, the caller either spins waiting
for the lock or gets queued. The locks are based in user address space
thus avoiding any system call overhead in the case where the lock is
available.
The actual algorithm used to implement these functions depends on whether
the system is a multiprocessor or a single processor. In the
multiprocessor case, if the lock is already locked, the caller will spin
(i.e. busy wait). The amount of time it spins depends on the function -
for ussetlock, a system chosen value is used, for uscsetlock and
uswsetlock the value of spins is used. If, after spins attempts to
acquire the lock have all failed, the function will either return
(uscsetlock) or yield the processor (ussetlock, or uswsetlock). The
yield is affected by calling sginap(2). After returning from yield,
ussetlock and uswsetlock will again attempt to acquire the lock spins
times. This will continue until the lock is finally acquired. Note that
if a process spends much of its time waiting for a lock without giving up
the processor, then the total throughput of the system may be reduced.
On the other hand, by giving up the processor too quickly, there is a
longer latency between when the lock is freed and the caller obtains the
lock.
Page 1
USSETLOCK(3P)USSETLOCK(3P)
The implementation of locks on single processor systems never spin; if
the lock is unavailable the caller is atomically queued. This queueing
operation suspends the calling process and forces a scheduling cycle.
Processes are removed from the queue in FIFO order when the lock is
released.
The appropriate lock algorithm is selected automatically at program
startup time. Different levels of debugging information can be requested
via usconfig(3P).
ussetlock doesn't return until the lock specified by lock is acquired.
uscsetlock attempts to acquire a lock spins times, returning a 1 if the
lock was acquired, and a 0 if it was not available. uswsetlock is
similar to ussetlock, except that the caller specifies the number of
times the lock is attempted to be acquired before the process gives up
control of the processor. On a single processor this call is identical
with ussetlock. ustestlock returns the instantaneous value of the lock,
a 0 if it is not locked, and a 1 if it is locked. usunsetlock releases
the lock.
When invoked with a valid lock, ussetlock and uswsetlock do not return
until the lock is acquired. An invalid lock will yield unpredictable
results.
It is allowed to call usunsetlock on a lock that is either not locked or
locked by another process. In either case, the lock will be unlocked.
Double tripping, i.e. calling a set lock function twice with the same
lock is also permissible. The caller will block until another process
unsets the lock.
In order to use a lock, the caller must have joined the shared arena out
of which the lock is allocated (via usinit(3P)), and have a file
descriptor to a usema(7M) device to suspend/unsuspend on. As a
convenience, these routines will automatically do this for members of a
share group, or for related (via fork(2)) processes. This automatic
facility can generate the same errors as usinit(3P). These errors will
be passed back to the caller. If tracing is enabled (see usinit(3P))
then any errors will cause a message to be printed to stderr. To avoid
these errors and therefore not need to check for errors on every lock
call, have each process call usinit(3P) before using any locks.
These locks are designed to be fast in the case where the lock is
available. On a Challenge R4400 multiprocessor a ussetlock, unsetlock
pair takes about 500nS.
When using debugging lock types the following debugging prints can occur.
Double tripped on lock @ 0x... by pid ... will be printed when an attempt
is made to acquire a lock that is already held by the caller.
Page 2
USSETLOCK(3P)USSETLOCK(3P)
Unlocking lock that other process lockd lock @ 0x... by pid ... will be
printed when an attempt is made to release a lock that is not held by the
process attempting to release it.
Unset lock, but lock not locked. lock @ 0x... pid ... will be printed
when using debug software locks, and an attempt was made to unlock a lock
that was not locked.
The following errors can occur due to misuse of a lock:
[EBADF] The underlying file descriptor for the lock was closed or
re-used by the application.
SEE ALSOsginap(2), barrier(3P), uscas(3P), usconfig(3P), usctllock(3P),
usdumplock(3P), usfreelock(3P), usinitlock(3P), usinit(3P), uspsema(3P).
usnewlock(3P), usnewsema(3P), usema(7M).
DIAGNOSTICS
ussetlock, uswsetlock, uscsetlock, and ustestlock will return a 1 if the
lock is acquired and a 0 if the lock is not acquired. usunsetlock always
returns 0 if successful. On error, -1 is returned and errno is set to
indicate the error.
Page 3
