diff options
Diffstat (limited to 'man/man3/pthread_spin_init.3')
| -rw-r--r-- | man/man3/pthread_spin_init.3 | 148 |
1 files changed, 148 insertions, 0 deletions
diff --git a/man/man3/pthread_spin_init.3 b/man/man3/pthread_spin_init.3 new file mode 100644 index 000000000..0a72c89a0 --- /dev/null +++ b/man/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 (date) "Linux man-pages (unreleased)" +.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) |