ld.so.8: srcfix

[thirdparty/man-pages.git] / man3 / pthread_spin_init.3

diff --git a/man3/pthread_spin_init.3 b/man3/pthread_spin_init.3
index 9aa87609bdf285bdbf05d5e83cf9af4ba4a83e88..ce47d428036a32fcd5fd58674f314c28457a0164 100644 (file)
--- a/man3/pthread_spin_init.3
+++ b/man3/pthread_spin_init.3
@@ -29,8 +29,8 @@ pthread_spin_init, pthread_spin_destroy \- initialize or destroy a spin lock
 .nf
 .B #include <pthread.h>
 .PP
-.BI "int pthread_spin_init(pthread_spinlock_t *" clock " int " pshared ");"
-.BI "int pthread_spin_destroy(pthread_spinlock_t *" clock ");"
+.BI "int pthread_spin_init(pthread_spinlock_t *" lock ", int " pshared ");"
+.BI "int pthread_spin_destroy(pthread_spinlock_t *" lock ");"
 .fi
 .PP
 Compile and link with \fI\-pthread\fP.
@@ -49,6 +49,13 @@ _POSIX_C_SOURCE >= 200112L
 .RE
 .ad
 .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
@@ -69,7 +76,7 @@ results in undefined behavior.)
 .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
+(i.e., the lock may be in a shared memory object that is
 shared among multiple processes).
 .PP
 Calling
@@ -90,6 +97,17 @@ 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 (3)
+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.
@@ -128,12 +146,24 @@ 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
-.BR Warning :
-if threads create a deadlock situation while employing spin locks,
+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)