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 processes. 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.