diff options
Diffstat (limited to 'man3/pthread_spin_init.3')
| -rw-r--r-- | man3/pthread_spin_init.3 | 148 |
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 0a72c89a0..000000000 --- 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 (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) |