PTHREAD_SPIN(3)

PTHREAD_SPIN(3) | Library Functions Manual | PTHREAD_SPIN(3)

# NAME

`pthread_spin`, `pthread_spin_init`, `pthread_spin_destroy`, `pthread_spin_lock`, `pthread_spin_trylock`, `pthread_spin_unlock` — 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.

July 8, 2010 | NetBSD 11.0