man3/pthread_spin_lock.3

   1 .\" Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH pthread_spin_lock 3 (date) "Linux man-pages (unreleased)"
   6 .SH NAME
   7 pthread_spin_lock, pthread_spin_trylock, pthread_spin_unlock \-
   8 lock and unlock a spin lock
   9 .SH LIBRARY
  10 POSIX threads library
  11 .RI ( libpthread ", " \-lpthread )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <pthread.h>
  15 .P
  16 .BI "int pthread_spin_lock(pthread_spinlock_t *" lock );
  17 .BI "int pthread_spin_trylock(pthread_spinlock_t *" lock );
  18 .BI "int pthread_spin_unlock(pthread_spinlock_t *" lock );
  19 .fi
  20 .P
  21 .RS -4
  22 Feature Test Macro Requirements for glibc (see
  23 .BR feature_test_macros (7)):
  24 .RE
  25 .P
  26 .BR pthread_spin_lock (),
  27 .BR pthread_spin_trylock ():
  28 .nf
  29     _POSIX_C_SOURCE >= 200112L
  30 .fi
  31 .SH DESCRIPTION
  32 The
  33 .BR pthread_spin_lock ()
  34 function locks the spin lock referred to by
  35 .IR lock .
  36 If the spin lock is currently unlocked,
  37 the calling thread acquires the lock immediately.
  38 If the spin lock is currently locked by another thread,
  39 the calling thread spins, testing the lock until it becomes available,
  40 at which point the calling thread acquires the lock.
  41 .P
  42 Calling
  43 .BR pthread_spin_lock ()
  44 on a lock that is already held by the caller
  45 or a lock that has not been initialized with
  46 .BR pthread_spin_init (3)
  47 results in undefined behavior.
  48 .P
  49 The
  50 .BR pthread_spin_trylock ()
  51 function is like
  52 .BR pthread_spin_lock (),
  53 except that if the spin lock referred to by
  54 .I lock
  55 is currently locked,
  56 then, instead of spinning, the call returns immediately with the error
  57 .BR EBUSY .
  58 .P
  59 The
  60 .BR pthread_spin_unlock ()
  61 function unlocks the spin lock referred to
  62 .IR lock .
  63 If any threads are spinning on the lock,
  64 one of those threads will then acquire the lock.
  65 .P
  66 Calling
  67 .BR pthread_spin_unlock ()
  68 on a lock that is not held by the caller results in undefined behavior.
  69 .SH RETURN VALUE
  70 On success, these functions return zero.
  71 On failure, they return an error number.
  72 .SH ERRORS
  73 .BR pthread_spin_lock ()
  74 may fail with the following errors:
  75 .TP
  76 .B EDEADLOCK
  77 .\" Not detected in glibc
  78 The system detected a deadlock condition.
  79 .P
  80 .BR pthread_spin_trylock ()
  81 fails with the following errors:
  82 .TP
  83 .B EBUSY
  84 The spin lock is currently locked by another thread.
  85 .SH STANDARDS
  86 POSIX.1-2008.
  87 .SH HISTORY
  88 glibc 2.2.
  89 POSIX.1-2001.
  90 .SH CAVEATS
  91 Applying any of the functions described on this page to
  92 an uninitialized spin lock results in undefined behavior.
  93 .P
  94 Carefully read NOTES in
  95 .BR pthread_spin_init (3).
  96 .SH SEE ALSO
  97 .ad l
  98 .nh
  99 .\" FIXME . .BR pthread_mutex_lock (3),
 100 .BR pthread_spin_destroy (3),
 101 .BR pthread_spin_init (3),
 102 .BR pthreads (7)