USSETLOCK(3P)                                                    USSETLOCK(3P)


NAME
     ussetlock, uscsetlock, uswsetlock, ustestlock, usunsetlock - spinlock
     routines

C SYNOPSIS
     #include <ulocks.h>

     int ussetlock (ulock_t lock);

     int uscsetlock (ulock_t lock, unsigned spins);

     int uswsetlock (ulock_t lock, unsigned spins);

     int ustestlock (ulock_t lock);

     int usunsetlock (ulock_t lock);

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,
     uscsetlock 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.

     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.

     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 ALSO
     sginap(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