pthread_spin_init(3) [freebsd man page]

PTHREAD_SPIN_INIT(3)					   BSD Library Functions Manual 				      PTHREAD_SPIN_INIT(3)

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);

DESCRIPTION

     The pthread_spin_init() function will initialize lock to an unlocked state and allocate any resources necessary to begin using it.  If
     pshared is set to PTHREAD_PROCESS_SHARED, any thread, whether belonging to the process in which the spinlock was created or not, that has
     access to the memory area where lock resides, can use lock.  If it is set to PTHREAD_PROCESS_PRIVATE, it can only be used by threads within
     the same process.

     The pthread_spin_destroy() function will destroy lock and release any resources that may have been allocated on its behalf.

RETURN VALUES

     If successful, both pthread_spin_init() and pthread_spin_destroy() will return zero.  Otherwise, an error number will be returned to indicate
     the error.

     Neither of these functions will return EINTR.

ERRORS

     The pthread_spin_init() and pthread_spin_destroy() functions will fail if:

     [EBUSY]		An attempt to initialize or destroy lock while it is in use.

     [EINVAL]		The value specified by lock is invalid.

     The pthread_spin_init() function will fail if:

     [EAGAIN]		Insufficient resources, other than memory, to initialize lock.

     [ENOMEM]		Insufficient memory to initialize lock.

SEE ALSO

     pthread_spin_lock(3), pthread_spin_unlock(3)

HISTORY

     The pthread_spin_init() and pthread_spin_destroy() functions first appeared in N:M Threading Library (libkse, -lkse) in FreeBSD 5.2, and in
     1:1 Threading Library (libthr, -lthr) in FreeBSD 5.3.

BUGS

     The implementation of pthread_spin_init() does not fully conform to IEEE Std 1003.2 (``POSIX.2'') because the pshared argument is ignored in
     1:1 Threading Library (libthr, -lthr), and in N:M Threading Library (libkse, -lkse) if any value other than PTHREAD_PROCESSES_PRIVATE is
     specified, it returns EINVAL.

BSD
								 January 22, 2004							       BSD

PTHREAD_SPIN(3) 					   BSD Library Functions Manual 					   PTHREAD_SPIN(3)

NAME

     pthread_spin -- spin lock interface

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);

     int
     pthread_spin_lock(pthread_spinlock_t *lock);

     int
     pthread_spin_trylock(pthread_spinlock_t *lock);

     int
     pthread_spin_unlock(pthread_spinlock_t *lock);

DESCRIPTION

     The pthread_spin_init() function is used to initialize a spin lock.  In the NetBSD implementation the pshared parameter is currently unused
     and all spin locks exhibit the PTHREAD_PROCESS_SHARED property, implying that all spin locks may be accessed by threads of multiple pro-
     cesses.  The results of calling pthread_spin_init() with an already initialized lock are undefined.

     The pthread_spin_destroy() function is used to destroy a spin lock previously created with pthread_spin_init().  It is undefined what happens
     if the function is called when a thread holds the lock, or if the function is called with an uninitialized spin lock.

     The pthread_spin_lock() function acquires a spin lock on lock, provided that lock is not presently held.  If the lock cannot be immediately
     acquired, the calling thread repeatedly retries until it can acquire the lock.  Undefined behavior may follow if the calling thread holds the
     lock at the time the call is made.

     The pthread_spin_trylock() function performs the same locking action, but does not block if the lock cannot be immediately obtained; if the
     lock is held, the call fails.

     The pthread_spin_unlock() function is used to release the read/write lock previously obtained by pthread_spin_lock() or
     pthread_spin_trylock().  The results are undefined if the lock is not held by the calling thread.

RETURN VALUES

     If successful, all described functions return zero.  Otherwise an error number will be returned to indicate the error.

ERRORS

     The pthread_spin_init() function shall fail if:

     [ENOMEM]		Insufficient memory exists to initialize the lock.

     The pthread_spin_init() function may fail if:

     [EINVAL]		The lock parameter was NULL or the pshared parameter was neither PTHREAD_PROCESS_SHARED nor PTHREAD_PROCESS_PRIVATE.

     The pthread_spin_destroy() function may fail if:

     [EBUSY]		The system has detected an attempt to destroy the object referenced by lock while it is locked.

     [EINVAL]		The value specified by lock is invalid.

     The pthread_spin_trylock() function shall fail if:

     [EBUSY]		The lock could not be acquired because a writer holds the lock or was blocked on it.

     The pthread_spin_lock() function may fail if:

     [EDEADLK]		The current thread already owns lock for writing.

     The pthread_spin_lock() and pthread_spin_trylock() functions may fail if:

     [EINVAL]		The value specified by lock is invalid.

     The pthread_spin_unlock() function may fail if:

     [EINVAL]		The value specified by lock is invalid.

SEE ALSO

     pthread(3), pthread_barrier(3), pthread_cond(3), pthread_mutex(3), pthread_rwlock(3)

STANDARDS

     These functions conform to IEEE Std 1003.1-2001 (``POSIX.1'').

CAVEATS

     Applications using spin locks are vulnerable to the effects of priority inversion.  Applications using real-time threads (SCHED_FIFO),
     (SCHED_RR) should not use these interfaces.  Outside carefully controlled environments, priority inversion with spin locks can lead to system
     deadlock.	Mutexes are preferable in nearly every possible use case.

BSD
								   July 8, 2010 							       BSD