# pthread_spin_init

## NAME



           pthread_spin_init, pthread_spin_destroy - initialize or destroy a
           spin lock
    


## LIBRARY



           POSIX threads library (_libpthread_ , _-lpthread_)
    


## SYNOPSIS



           **#include <pthread.h>**
    
           **int pthread_spin_init(pthread_spinlock_t ***_lock_**, int** _pshared_**);**
           **int pthread_spin_destroy(pthread_spinlock_t ***_lock_**);**
    
       Feature Test Macro Requirements for glibc (see
       feature_test_macros(7)):
    
           **pthread_spin_init**(), **pthread_spin_destroy**():
               _POSIX_C_SOURCE >= 200112L
    


## DESCRIPTION



           _General note_ : Most programs should use mutexes instead of spin
           locks.  Spin locks are primarily useful in conjunction with real-
           time scheduling policies.  See NOTES.
    
           The **pthread_spin_init**() function allocates any resources required
           for the use of the spin lock referred to by _lock_ and initializes
           the lock to be in the unlocked state.  The _pshared_ argument must
           have one of the following values:
    
           **PTHREAD_PROCESS_PRIVATE**
                  The spin lock is to be operated on only by threads in the
                  same process as the thread that calls **pthread_spin_init**().
                  (Attempting to share the spin lock between processes
                  results in undefined behavior.)
    
           **PTHREAD_PROCESS_SHARED**
                  The spin lock may be operated on by any thread in any
                  process that has access to the memory containing the lock
                  (i.e., the lock may be in a shared memory object that is
                  shared among multiple processes).
    
           Calling **pthread_spin_init**() on a spin lock that has already been
           initialized results in undefined behavior.
    
           The **pthread_spin_destroy**() function destroys a previously
           initialized spin lock, freeing any resources that were allocated
           for that lock.  Destroying a spin lock that has not been
           previously been initialized or destroying a spin lock while
           another thread holds the lock results in undefined behavior.
    
           Once a spin lock has been destroyed, performing any operation on
           the lock other than once more initializing it with
           **pthread_spin_init**() results in undefined behavior.
    
           The result of performing operations such as pthread_spin_lock(3),
           pthread_spin_unlock(3), and **pthread_spin_destroy**() on _copies_ of
           the object referred to by _lock_ is undefined.
    


## RETURN VALUE



           On success, there functions return zero.  On failure, they return
           an error number.  In the event that **pthread_spin_init**() fails, the
           lock is not initialized.
    


## ERRORS



           **pthread_spin_init**() may fail with the following errors:
    
           **EAGAIN** The system has insufficient resources to initialize a new
                  spin lock.
    
           **ENOMEM** Insufficient memory to initialize the spin lock.
    


## STANDARDS



           POSIX.1-2008.
    


## NOTES



           Spin locks should be employed in conjunction with real-time
           scheduling policies (**SCHED_FIFO** , or possibly **SCHED_RR**).  Use of
           spin locks with nondeterministic scheduling policies such as
           **SCHED_OTHER** probably indicates a design mistake.  The problem is
           that if a thread operating under such a policy is scheduled off
           the CPU while it holds a spin lock, then other threads will waste
           time spinning on the lock until the lock holder is once more
           rescheduled and releases the lock.
    
           If threads create a deadlock situation while employing spin locks,
           those threads will spin forever consuming CPU time.
    
           User-space spin locks are _not_ applicable as a general locking
           solution.  They are, by definition, prone to priority inversion
           and unbounded spin times.  A programmer using spin locks must be
           exceptionally careful not only in the code, but also in terms of
           system configuration, thread placement, and priority assignment.
    


* * *