spinlock(3X)                                                   spinlock(3X)

NAME
     spinlock, initspin, spinunlock, cspinlock, yield - user synchroniza-
     tion primitives

SYNOPSIS
     cc [flag ...] file ... -lmproc

     #include <ulocks.h>

     void initspin(spinlockt *lck, long spincnt);

     void spinlock(spinlockt *lck);

     void spinunlock(spinlockt *lck);

     int cspinlock(spinlockt *lck);

     void yield();

DESCRIPTION
     The most fundamental synchronization primitive for a multiprocessor is
     the simple spin lock, which is the essence of other synchronization
     primitives. This primitive is dependent upon an atomic read-modify-
     write operation that supplied by the system. Different CPU architec-
     tures provide this capability in different ways and various system
     architectures support this capability by varying means. Typically,
     these low-level operations are coded in machine language. To hide the
     vagaries of these implementations across machines a basic set of prim-
     itives is provided.

     Typically, these primitives will be used by cooperating processes that
     share address space (such as shared memory) to control access to
     shared resources and data structures. The data structure that is the
     target of the primitives is shown below.

        typedef struct spinlock {
            volatile int   sllock;
            long           slscount;
         } spinlockt;

     The initialization primitive, initspin(), initializes a target lock
     for use by the primitives. initspin() takes two arguments: lck is a
     pointer to the target spinlockt data structure and spincnt is the
     number of spins that will be attempted on a lock acquisition,
     spinlock(), before the calling process yields the CPU. Setting spincnt
     to -1 implies an infinite number of spins (the process will not yield
     the CPU voluntarily).








Page 1                       Reliant UNIX 5.44                Printed 11/98

spinlock(3X)                                                   spinlock(3X)

     The spinlock() acquisition function attempts to acquire the lock
     designated by lck. This function will either spin for some number
     iterations (determined by the spincnt initialization parameter) before
     giving up and yielding the CPU or spins indefinitely (spincnt is -1)
     until the lock is acquired bearing in mind that the operating system
     may choose to time slice the process out at any time.

     The spinunlock() function releases (unlocks) the lock designated by
     lck and has the opposite effect to spinlock().

     The conditional spin lock operation, cspinlock(), attempts to acquire
     the target lock, lck and returns status indicating the disposition of
     the lock. If the lock is already held, the primitive does not spin on
     the acquisition and failure is returned (non-zero). If the lock is
     available, it is acquired and success is returned (zero).

     The yield() primitive allows the caller to relinquish the CPU (imple-
     mented through the mpcntlyield option to mpcnt()) without actually
     blocking. This function may return immediately if the calling process
     has high enough priority to allow it to continue execution.

SEE ALSO
     mpcntl(3X).































Page 2                       Reliant UNIX 5.44                Printed 11/98