|
Packit |
7cfc04 |
.\" Copyright (c) 2017, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(VERBATIM)
|
|
Packit |
7cfc04 |
.\" Permission is granted to make and distribute verbatim copies of this
|
|
Packit |
7cfc04 |
.\" manual provided the copyright notice and this permission notice are
|
|
Packit |
7cfc04 |
.\" preserved on all copies.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Permission is granted to copy and distribute modified versions of this
|
|
Packit |
7cfc04 |
.\" manual under the conditions for verbatim copying, provided that the
|
|
Packit |
7cfc04 |
.\" entire resulting derived work is distributed under the terms of a
|
|
Packit |
7cfc04 |
.\" permission notice identical to this one.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
Packit |
7cfc04 |
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
Packit |
7cfc04 |
.\" responsibility for errors or omissions, or for damages resulting from
|
|
Packit |
7cfc04 |
.\" the use of the information contained herein. The author(s) may not
|
|
Packit |
7cfc04 |
.\" have taken the same level of care in the production of this manual,
|
|
Packit |
7cfc04 |
.\" which is licensed free of charge, as they might when working
|
|
Packit |
7cfc04 |
.\" professionally.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
Packit |
7cfc04 |
.\" the source, must acknowledge the copyright and authors of this work.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.TH PTHREAD_SPIN_INIT 3 2017-09-30 "Linux" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
pthread_spin_init, pthread_spin_destroy \- initialize or destroy a spin lock
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
.B #include <pthread.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "int pthread_spin_init(pthread_spinlock_t *" lock " int " pshared ");"
|
|
Packit |
7cfc04 |
.BI "int pthread_spin_destroy(pthread_spinlock_t *" lock ");"
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Compile and link with \fI\-pthread\fP.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in -4n
|
|
Packit |
7cfc04 |
Feature Test Macro Requirements for glibc (see
|
|
Packit |
7cfc04 |
.BR feature_test_macros (7)):
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BR pthread_spin_init (),
|
|
Packit |
7cfc04 |
.BR pthread_spin_destroy ():
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.ad l
|
|
Packit |
7cfc04 |
_POSIX_C_SOURCE >= 200112L
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.ad
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
.IR "General note" :
|
|
Packit |
7cfc04 |
Most programs should use mutexes
|
|
Packit |
7cfc04 |
instead of spin locks.
|
|
Packit |
7cfc04 |
Spin locks are primarily useful in conjunction with real-time
|
|
Packit |
7cfc04 |
scheduling policies.
|
|
Packit |
7cfc04 |
See NOTES.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR pthread_spin_init ()
|
|
Packit |
7cfc04 |
function allocates any resources required for the use of
|
|
Packit |
7cfc04 |
the spin lock referred to by
|
|
Packit |
7cfc04 |
.I lock
|
|
Packit |
7cfc04 |
and initializes the lock to be in the unlocked state.
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I pshared
|
|
Packit |
7cfc04 |
argument must have one of the following values:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B PTHREAD_PROCESS_PRIVATE
|
|
Packit |
7cfc04 |
The spin lock is to be operated on only by threads in the same process
|
|
Packit |
7cfc04 |
as the thread that calls
|
|
Packit |
7cfc04 |
.BR pthread_spin_init ().
|
|
Packit |
7cfc04 |
(Attempting to share the spin lock between processes
|
|
Packit |
7cfc04 |
results in undefined behavior.)
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B PTHREAD_PROCESS_SHARED
|
|
Packit |
7cfc04 |
The spin lock may be operated on by any thread in any process that
|
|
Packit |
7cfc04 |
has access to the memory containing the lock
|
|
Packit |
7cfc04 |
(i.e., the lock may be in a shared memory object that is
|
|
Packit |
7cfc04 |
shared among multiple processes).
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Calling
|
|
Packit |
7cfc04 |
.BR pthread_spin_init ()
|
|
Packit |
7cfc04 |
on a spin lock that has already been initialized results
|
|
Packit |
7cfc04 |
in undefined behavior.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR pthread_spin_destroy ()
|
|
Packit |
7cfc04 |
function destroys a previously initialized spin lock,
|
|
Packit |
7cfc04 |
freeing any resources that were allocated for that lock.
|
|
Packit |
7cfc04 |
Destroying a spin lock that has not been previously been initialized
|
|
Packit |
7cfc04 |
or destroying a spin lock while another thread holds the lock
|
|
Packit |
7cfc04 |
results in undefined behavior.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Once a spin lock has been destroyed,
|
|
Packit |
7cfc04 |
performing any operation on the lock other than
|
|
Packit |
7cfc04 |
once more initializing it with
|
|
Packit |
7cfc04 |
.BR pthread_spin_init ()
|
|
Packit |
7cfc04 |
results in undefined behavior.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The result of performing operations such as
|
|
Packit |
7cfc04 |
.BR pthread_spin_lock (3),
|
|
Packit |
7cfc04 |
.BR pthread_spin_unlock (3),
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR pthread_spin_destroy (3)
|
|
Packit |
7cfc04 |
on
|
|
Packit |
7cfc04 |
.I copies
|
|
Packit |
7cfc04 |
of the object referred to by
|
|
Packit |
7cfc04 |
.I lock
|
|
Packit |
7cfc04 |
is undefined.
|
|
Packit |
7cfc04 |
.SH RETURN VALUE
|
|
Packit |
7cfc04 |
On success, there functions return zero.
|
|
Packit |
7cfc04 |
On failure, they return an error number.
|
|
Packit |
7cfc04 |
In the event that
|
|
Packit |
7cfc04 |
.BR pthread_spin_init ()
|
|
Packit |
7cfc04 |
fails, the lock is not initialized.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
.BR pthread_spin_init ()
|
|
Packit |
7cfc04 |
may fail with the following errors:
|
|
Packit |
7cfc04 |
.\" These errors don't occur on the glibc implementation
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EAGAIN
|
|
Packit |
7cfc04 |
The system has insufficient resources to initialize
|
|
Packit |
7cfc04 |
a new spin lock.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ENOMEM
|
|
Packit |
7cfc04 |
Insufficient memory to initialize the spin lock.
|
|
Packit |
7cfc04 |
.SH VERSIONS
|
|
Packit |
7cfc04 |
These functions first appeared in glibc in version 2.2.
|
|
Packit |
7cfc04 |
.SH CONFORMING TO
|
|
Packit |
7cfc04 |
POSIX.1-2001.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Support for process-shared spin locks is a POSIX option.
|
|
Packit |
7cfc04 |
The option is supported in the glibc implementation.
|
|
Packit |
7cfc04 |
.SH NOTES
|
|
Packit |
7cfc04 |
Spin locks should be employed in conjunction with
|
|
Packit |
7cfc04 |
real-time scheduling policies
|
|
Packit |
7cfc04 |
.RB ( SCHED_FIFO ,
|
|
Packit |
7cfc04 |
or possibly
|
|
Packit |
7cfc04 |
.BR SCHED_RR ).
|
|
Packit |
7cfc04 |
Use of spin locks with nondeterministic scheduling policies such as
|
|
Packit |
7cfc04 |
.BR SCHED_OTHER
|
|
Packit |
7cfc04 |
probably indicates a design mistake.
|
|
Packit |
7cfc04 |
The problem is that if a thread operating under such a policy
|
|
Packit |
7cfc04 |
is scheduled off the CPU while it holds a spin lock,
|
|
Packit |
7cfc04 |
then other threads will waste time spinning on the lock
|
|
Packit |
7cfc04 |
until the lock holder is once more rescheduled and releases the lock.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If threads create a deadlock situation while employing spin locks,
|
|
Packit |
7cfc04 |
those threads will spin forever consuming CPU time.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
User-space spin locks are
|
|
Packit |
7cfc04 |
.I not
|
|
Packit |
7cfc04 |
applicable as a general locking solution.
|
|
Packit |
7cfc04 |
They are, by definition,
|
|
Packit |
7cfc04 |
prone to priority inversion and unbounded spin times.
|
|
Packit |
7cfc04 |
A programmer using spin locks must be exceptionally careful not
|
|
Packit |
7cfc04 |
only in the code, but also in terms of system configuration,
|
|
Packit |
7cfc04 |
thread placement, and priority assignment.
|
|
Packit |
7cfc04 |
.\" FIXME . When PTHREAD_MUTEX_ADAPTIVE_NP is one day document
|
|
Packit |
7cfc04 |
.\" make reference to it here
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.ad l
|
|
Packit |
7cfc04 |
.nh
|
|
Packit |
7cfc04 |
.BR pthread_mutex_init (3),
|
|
Packit |
7cfc04 |
.BR pthread_mutex_lock (3),
|
|
Packit |
7cfc04 |
.BR pthread_spin_lock (3),
|
|
Packit |
7cfc04 |
.BR pthread_spin_unlock (3),
|
|
Packit |
7cfc04 |
.BR pthreads (7)
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|