Adding upstream version 6.05.01.upstream/6.05.01

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 148 insertions, 0 deletions

diff --git a/man3/pthread_spin_init.3 b/man3/pthread_spin_init.3
new file mode 100644
index 0000000..87ad2e8
--- /dev/null
+++ b/man3/pthread_spin_init.3
@@ -0,0 +1,148 @@
+.\" Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pthread_spin_init 3 2023-03-30 "Linux man-pages 6.05.01"
+.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>
+.PP
+.BI "int pthread_spin_init(pthread_spinlock_t *" lock ", int " pshared ");"
+.BI "int pthread_spin_destroy(pthread_spinlock_t *" lock ");"
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.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.
+.PP
+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).
+.PP
+Calling
+.BR pthread_spin_init ()
+on a spin lock that has already been initialized results
+in undefined behavior.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+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.
+.PP
+If threads create a deadlock situation while employing spin locks,
+those threads will spin forever consuming CPU time.
+.PP
+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)