man3/pthread_spin_init.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_INIT 3 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
   6 .SH NAME
   7 pthread_spin_init, pthread_spin_destroy \- initialize or destroy a spin lock
   8 .SH LIBRARY
   9 POSIX threads library
  10 .RI ( libpthread ", " \-lpthread )
  11 .SH SYNOPSIS
  12 .nf
  13 .B #include <pthread.h>
  14 .PP
  15 .BI "int pthread_spin_init(pthread_spinlock_t *" lock ", int " pshared ");"
  16 .BI "int pthread_spin_destroy(pthread_spinlock_t *" lock ");"
  17 .fi
  18 .PP
  19 .RS -4
  20 Feature Test Macro Requirements for glibc (see
  21 .BR feature_test_macros (7)):
  22 .RE
  23 .PP
  24 .BR pthread_spin_init (),
  25 .BR pthread_spin_destroy ():
  26 .nf
  27     _POSIX_C_SOURCE >= 200112L
  28 .fi
  29 .SH DESCRIPTION
  30 .IR "General note" :
  31 Most programs should use mutexes
  32 instead of spin locks.
  33 Spin locks are primarily useful in conjunction with real-time
  34 scheduling policies.
  35 See NOTES.
  36 .PP
  37 The
  38 .BR pthread_spin_init ()
  39 function allocates any resources required for the use of
  40 the spin lock referred to by
  41 .I lock
  42 and initializes the lock to be in the unlocked state.
  43 The
  44 .I pshared
  45 argument must have one of the following values:
  46 .TP
  47 .B PTHREAD_PROCESS_PRIVATE
  48 The spin lock is to be operated on only by threads in the same process
  49 as the thread that calls
  50 .BR pthread_spin_init ().
  51 (Attempting to share the spin lock between processes
  52 results in undefined behavior.)
  53 .TP
  54 .B PTHREAD_PROCESS_SHARED
  55 The spin lock may be operated on by any thread in any process that
  56 has access to the memory containing the lock
  57 (i.e., the lock may be in a shared memory object that is
  58 shared among multiple processes).
  59 .PP
  60 Calling
  61 .BR pthread_spin_init ()
  62 on a spin lock that has already been initialized results
  63 in undefined behavior.
  64 .PP
  65 The
  66 .BR pthread_spin_destroy ()
  67 function destroys a previously initialized spin lock,
  68 freeing any resources that were allocated for that lock.
  69 Destroying a spin lock that has not been previously been initialized
  70 or destroying a spin lock while another thread holds the lock
  71 results in undefined behavior.
  72 .PP
  73 Once a spin lock has been destroyed,
  74 performing any operation on the lock other than
  75 once more initializing it with
  76 .BR pthread_spin_init ()
  77 results in undefined behavior.
  78 .PP
  79 The result of performing operations such as
  80 .BR pthread_spin_lock (3),
  81 .BR pthread_spin_unlock (3),
  82 and
  83 .BR pthread_spin_destroy ()
  84 on
  85 .I copies
  86 of the object referred to by
  87 .I lock
  88 is undefined.
  89 .SH RETURN VALUE
  90 On success, there functions return zero.
  91 On failure, they return an error number.
  92 In the event that
  93 .BR pthread_spin_init ()
  94 fails, the lock is not initialized.
  95 .SH ERRORS
  96 .BR pthread_spin_init ()
  97 may fail with the following errors:
  98 .\" These errors don't occur on the glibc implementation
  99 .TP
 100 .B EAGAIN
 101 The system has insufficient resources to initialize
 102 a new spin lock.
 103 .TP
 104 .B ENOMEM
 105 Insufficient memory to initialize the spin lock.
 106 .SH VERSIONS
 107 These functions first appeared in glibc in version 2.2.
 108 .SH STANDARDS
 109 POSIX.1-2001.
 110 .PP
 111 Support for process-shared spin locks is a POSIX option.
 112 The option is supported in the glibc implementation.
 113 .SH NOTES
 114 Spin locks should be employed in conjunction with
 115 real-time scheduling policies
 116 .RB ( SCHED_FIFO ,
 117 or possibly
 118 .BR SCHED_RR ).
 119 Use of spin locks with nondeterministic scheduling policies such as
 120 .B SCHED_OTHER
 121 probably indicates a design mistake.
 122 The problem is that if a thread operating under such a policy
 123 is scheduled off the CPU while it holds a spin lock,
 124 then other threads will waste time spinning on the lock
 125 until the lock holder is once more rescheduled and releases the lock.
 126 .PP
 127 If threads create a deadlock situation while employing spin locks,
 128 those threads will spin forever consuming CPU time.
 129 .PP
 130 User-space spin locks are
 131 .I not
 132 applicable as a general locking solution.
 133 They are, by definition,
 134 prone to priority inversion and unbounded spin times.
 135 A programmer using spin locks must be exceptionally careful not
 136 only in the code, but also in terms of system configuration,
 137 thread placement, and priority assignment.
 138 .\" FIXME . When PTHREAD_MUTEX_ADAPTIVE_NP is one day document
 139 .\" make reference to it here
 140 .SH SEE ALSO
 141 .ad l
 142 .nh
 143 .BR pthread_mutex_init (3),
 144 .BR pthread_mutex_lock (3),
 145 .BR pthread_spin_lock (3),
 146 .BR pthread_spin_unlock (3),
 147 .BR pthreads (7)