_spin(3synch)                                          _spin(3synch)


       NAME
             _spin: _spin_init, _spin_lock, _spin_trylock, _spin_unlock,
             _spin_destroy - overview of spin lock routines

       SYNOPSIS
             cc [options] -Kthread file
             #include <synch.h>
             int _spin_init(spin_t *lock, void *arg);
             void _spin_lock(spin_t *lock);
             int _spin_trylock(spin_t *lock);
             void _spin_unlock(spin_t *lock);
             int _spin_destroy(spin_t *lock);

          Parameters
             lock   pointer to spin lock to be initialized, locked,
                    unlocked, or destroyed

             arg    NULL (reserved for future use)

       DESCRIPTION
             Spin locks, a type of mutual exclusion lock (mutex), are used
             to serialize the execution of threads.  They are typically
             used to ensure that only one thread at a time accesses shared
             data.  Note that these locks protect data only when the
             convention of acquiring the lock is faithfully followed before
             any access of the data.

             The difference between spin locks and ordinary mutex locks is
             in their locking routines.  When a mutex is already locked,
             the locking routine (mutex_lock) will block the caller until
             the lock is available.  When a spin lock is already locked,
             the locking routine (_spin_lock) will busy-wait, or spin, in a
             loop, testing if the lock has become available.  Such spinning
             wastes processor cycles and can slow processors doing useful
             work, including the processor holding the lock, by consuming
             communication bandwidth.

             The Threads Library provides five routines to manipulate spin
             locks; these are outlined below and described in more detail
             on individual manual pages.

          _spin_init
             _spin_init initializes the spin lock pointed to by lock to the
             unlocked state.




                           Copyright 1994 Novell, Inc.               Page 1

      _spin(3synch)                                          _spin(3synch)


         _spin_lock
            _spin_lock locks the spin lock pointed to by lock.  If lock is
            locked, the calling thread will busy-wait, or spin, until lock
            is available.  When _spin_lock returns, the caller has
            acquired lock.

         _spin_trylock
            _spin_trylock attempts once to lock the spin lock pointed to
            by lock.

            If lock is available, _spin_trylock will return successfully
            with lock locked.  If lock is already locked, _spin_trylock
            immediately returns EBUSY to the caller without acquiring lock
            or spinning.

         _spin_unlock
            _spin_unlock unlocks the spin lock pointed to by lock.

            If one or more threads are waiting for the lock when
            _spin_unlock is called, one of the waiting threads will
            acquire the lock.

         _spin_destroy
            _spin_destroy destroys the spin lock pointed to by lock.  This
            includes invalidating lock and freeing any associated
            implementation-allocated dynamic resources.

      USAGE
            Because spin locks waste system resources, most applications
            should use mutexes instead of spin locks for mutual exclusion.
            However, spin locks are useful when:

                  sleep is not permitted

                  the critical section is small, so that the expected spin
                  is less costly than blocking and resuming the thread

                  no other work is available

            Spin locks should only be used when there is a guarantee that
            the thread will not be preempted or blocked while holding a
            spin lock.  It is the responsibility of each application to
            unlock all spin locks before calling sleep or blocking
            routines.




                          Copyright 1994 Novell, Inc.               Page 2

       _spin(3synch)                                          _spin(3synch)


          Warnings
             Spin locks must not be used on a uniprocessor.  In the best
             case, a spin lock on a uniprocessor will waste resources,
             slowing down the owner of the lock; in the worst case, it will
             deadlock the processor.

             Operations on spin locks are not recursive-a thread can
             deadlock if it attempts to relock a spin lock that it already
             has locked.

       REFERENCES
             mutex(3synch), _spin_destroy(3synch), _spin_init(3synch),
             _spin_lock(3synch), _spin_trylock(3synch),
             _spin_unlock(3synch), synch(3synch)


































                           Copyright 1994 Novell, Inc.               Page 3