2017-09-30 10:50:58 +00:00
|
|
|
.\" Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
|
|
.\"
|
|
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
|
|
|
.\"
|
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
|
|
|
.\"
|
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\" %%%LICENSE_END
|
|
|
|
.\"
|
|
|
|
.TH PTHREAD_SPIN_INIT 3 2017-09-30 "Linux" "Linux Programmer's Manual"
|
|
|
|
.SH NAME
|
|
|
|
pthread_spin_init, pthread_spin_destroy \- initialize or destroy a spin lock
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.B #include <pthread.h>
|
|
|
|
.PP
|
2019-05-16 17:20:09 +00:00
|
|
|
.BI "int pthread_spin_init(pthread_spinlock_t *" lock ", int " pshared ");"
|
2017-10-21 20:21:30 +00:00
|
|
|
.BI "int pthread_spin_destroy(pthread_spinlock_t *" lock ");"
|
2017-09-30 10:50:58 +00:00
|
|
|
.fi
|
|
|
|
.PP
|
|
|
|
Compile and link with \fI\-pthread\fP.
|
|
|
|
.PP
|
|
|
|
.in -4n
|
|
|
|
Feature Test Macro Requirements for glibc (see
|
|
|
|
.BR feature_test_macros (7)):
|
|
|
|
.in
|
|
|
|
.PP
|
|
|
|
.BR pthread_spin_init (),
|
|
|
|
.BR pthread_spin_destroy ():
|
|
|
|
.br
|
|
|
|
.RS 4
|
|
|
|
.ad l
|
|
|
|
_POSIX_C_SOURCE >= 200112L
|
|
|
|
.RE
|
|
|
|
.ad
|
|
|
|
.SH DESCRIPTION
|
2017-10-19 20:04:44 +00:00
|
|
|
.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
|
2017-09-30 10:50:58 +00:00
|
|
|
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
|
2017-10-19 18:49:26 +00:00
|
|
|
(i.e., the lock may be in a shared memory object that is
|
2017-09-30 10:50:58 +00:00
|
|
|
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.
|
2017-10-19 19:07:08 +00:00
|
|
|
.PP
|
|
|
|
The result of performing operations such as
|
|
|
|
.BR pthread_spin_lock (3),
|
|
|
|
.BR pthread_spin_unlock (3),
|
|
|
|
and
|
|
|
|
.BR pthread_spin_destroy (3)
|
|
|
|
on
|
|
|
|
.I copies
|
|
|
|
of the object referred to by
|
|
|
|
.I lock
|
|
|
|
is undefined.
|
2017-09-30 10:50:58 +00:00
|
|
|
.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 VERSIONS
|
|
|
|
These functions first appeared in glibc in version 2.2.
|
|
|
|
.SH CONFORMING TO
|
|
|
|
POSIX.1-2001.
|
|
|
|
.PP
|
|
|
|
Support for process-shared spin locks is a POSIX option.
|
|
|
|
The option is supported in the glibc implementation.
|
2017-10-02 20:36:50 +00:00
|
|
|
.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
|
|
|
|
.BR 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.
|
2017-10-02 20:40:48 +00:00
|
|
|
.PP
|
2017-10-19 21:12:54 +00:00
|
|
|
If threads create a deadlock situation while employing spin locks,
|
2017-10-02 20:40:48 +00:00
|
|
|
those threads will spin forever consuming CPU time.
|
2017-10-19 21:12:54 +00:00
|
|
|
.PP
|
2017-10-20 07:27:32 +00:00
|
|
|
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.
|
2017-10-19 21:12:54 +00:00
|
|
|
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.
|
2017-10-20 08:18:56 +00:00
|
|
|
.\" FIXME . When PTHREAD_MUTEX_ADAPTIVE_NP is one day document
|
|
|
|
.\" make reference to it here
|
2017-09-30 10:50:58 +00:00
|
|
|
.SH SEE ALSO
|
|
|
|
.ad l
|
|
|
|
.nh
|
2017-10-19 20:04:44 +00:00
|
|
|
.BR pthread_mutex_init (3),
|
|
|
|
.BR pthread_mutex_lock (3),
|
2017-09-30 10:50:58 +00:00
|
|
|
.BR pthread_spin_lock (3),
|
|
|
|
.BR pthread_spin_unlock (3),
|
|
|
|
.BR pthreads (7)
|