summaryrefslogtreecommitdiffstats
path: root/man3/pthread_spin_init.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/pthread_spin_init.3')
-rw-r--r--man3/pthread_spin_init.3148
1 files changed, 0 insertions, 148 deletions
diff --git a/man3/pthread_spin_init.3 b/man3/pthread_spin_init.3
deleted file mode 100644
index 57ccb88..0000000
--- a/man3/pthread_spin_init.3
+++ /dev/null
@@ -1,148 +0,0 @@
-.\" Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com>
-.\"
-.\" SPDX-License-Identifier: Linux-man-pages-copyleft
-.\"
-.TH pthread_spin_init 3 2023-10-31 "Linux man-pages 6.7"
-.SH NAME
-pthread_spin_init, pthread_spin_destroy \- initialize or destroy a spin lock
-.SH LIBRARY
-POSIX threads library
-.RI ( libpthread ", " \-lpthread )
-.SH SYNOPSIS
-.nf
-.B #include <pthread.h>
-.P
-.BI "int pthread_spin_init(pthread_spinlock_t *" lock ", int " pshared ");"
-.BI "int pthread_spin_destroy(pthread_spinlock_t *" lock ");"
-.fi
-.P
-.RS -4
-Feature Test Macro Requirements for glibc (see
-.BR feature_test_macros (7)):
-.RE
-.P
-.BR pthread_spin_init (),
-.BR pthread_spin_destroy ():
-.nf
- _POSIX_C_SOURCE >= 200112L
-.fi
-.SH DESCRIPTION
-.IR "General note" :
-Most programs should use mutexes
-instead of spin locks.
-Spin locks are primarily useful in conjunction with real-time
-scheduling policies.
-See NOTES.
-.P
-The
-.BR pthread_spin_init ()
-function allocates any resources required for the use of
-the spin lock referred to by
-.I lock
-and initializes the lock to be in the unlocked state.
-The
-.I pshared
-argument must have one of the following values:
-.TP
-.B PTHREAD_PROCESS_PRIVATE
-The spin lock is to be operated on only by threads in the same process
-as the thread that calls
-.BR pthread_spin_init ().
-(Attempting to share the spin lock between processes
-results in undefined behavior.)
-.TP
-.B PTHREAD_PROCESS_SHARED
-The spin lock may be operated on by any thread in any process that
-has access to the memory containing the lock
-(i.e., the lock may be in a shared memory object that is
-shared among multiple processes).
-.P
-Calling
-.BR pthread_spin_init ()
-on a spin lock that has already been initialized results
-in undefined behavior.
-.P
-The
-.BR pthread_spin_destroy ()
-function destroys a previously initialized spin lock,
-freeing any resources that were allocated for that lock.
-Destroying a spin lock that has not been previously been initialized
-or destroying a spin lock while another thread holds the lock
-results in undefined behavior.
-.P
-Once a spin lock has been destroyed,
-performing any operation on the lock other than
-once more initializing it with
-.BR pthread_spin_init ()
-results in undefined behavior.
-.P
-The result of performing operations such as
-.BR pthread_spin_lock (3),
-.BR pthread_spin_unlock (3),
-and
-.BR pthread_spin_destroy ()
-on
-.I copies
-of the object referred to by
-.I lock
-is undefined.
-.SH RETURN VALUE
-On success, there functions return zero.
-On failure, they return an error number.
-In the event that
-.BR pthread_spin_init ()
-fails, the lock is not initialized.
-.SH ERRORS
-.BR pthread_spin_init ()
-may fail with the following errors:
-.\" These errors don't occur on the glibc implementation
-.TP
-.B EAGAIN
-The system has insufficient resources to initialize
-a new spin lock.
-.TP
-.B ENOMEM
-Insufficient memory to initialize the spin lock.
-.SH STANDARDS
-POSIX.1-2008.
-.SH HISTORY
-glibc 2.2.
-POSIX.1-2001.
-.P
-Support for process-shared spin locks is a POSIX option.
-The option is supported in the glibc implementation.
-.SH NOTES
-Spin locks should be employed in conjunction with
-real-time scheduling policies
-.RB ( SCHED_FIFO ,
-or possibly
-.BR SCHED_RR ).
-Use of spin locks with nondeterministic scheduling policies such as
-.B SCHED_OTHER
-probably indicates a design mistake.
-The problem is that if a thread operating under such a policy
-is scheduled off the CPU while it holds a spin lock,
-then other threads will waste time spinning on the lock
-until the lock holder is once more rescheduled and releases the lock.
-.P
-If threads create a deadlock situation while employing spin locks,
-those threads will spin forever consuming CPU time.
-.P
-User-space spin locks are
-.I not
-applicable as a general locking solution.
-They are, by definition,
-prone to priority inversion and unbounded spin times.
-A programmer using spin locks must be exceptionally careful not
-only in the code, but also in terms of system configuration,
-thread placement, and priority assignment.
-.\" FIXME . When PTHREAD_MUTEX_ADAPTIVE_NP is one day document
-.\" make reference to it here
-.SH SEE ALSO
-.ad l
-.nh
-.BR pthread_mutex_init (3),
-.BR pthread_mutex_lock (3),
-.BR pthread_spin_lock (3),
-.BR pthread_spin_unlock (3),
-.BR pthreads (7)