Module Name: src Committed By: rmind Date: Thu Jul 8 19:20:34 UTC 2010
Modified Files: src/distrib/sets/lists/comp: mi src/lib/libpthread: Makefile Added Files: src/lib/libpthread: pthread_barrier.3 pthread_cond.3 pthread_mutex.3 pthread_rwlock.3 pthread_spin.3 Removed Files: src/lib/libpthread: pthread_barrier_destroy.3 pthread_barrier_init.3 pthread_barrier_wait.3 pthread_cond_broadcast.3 pthread_cond_destroy.3 pthread_cond_init.3 pthread_cond_wait.3 pthread_mutex_destroy.3 pthread_mutex_init.3 pthread_mutex_lock.3 pthread_mutex_unlock.3 pthread_rwlock_destroy.3 pthread_rwlock_init.3 pthread_rwlock_rdlock.3 pthread_rwlock_unlock.3 pthread_rwlock_wrlock.3 pthread_spin_destroy.3 pthread_spin_init.3 pthread_spin_lock.3 pthread_spin_unlock.3 Log Message: Merge/group man pages: - pthread_barrier_{init,destroy,wait} into pthread_barrier(3). - pthread_cond_* into pthread_cond(3). - pthread_mutex_* into pthread_mutex(3). - pthread_rwlock_* into pthread_rwlock(3). - pthread_spin_* into pthread_spin(3). Cross-link amongst groups. OK jruoho@ To generate a diff of this commit: cvs rdiff -u -r1.1480 -r1.1481 src/distrib/sets/lists/comp/mi cvs rdiff -u -r1.65 -r1.66 src/lib/libpthread/Makefile cvs rdiff -u -r0 -r1.1 src/lib/libpthread/pthread_barrier.3 \ src/lib/libpthread/pthread_cond.3 src/lib/libpthread/pthread_mutex.3 \ src/lib/libpthread/pthread_rwlock.3 src/lib/libpthread/pthread_spin.3 cvs rdiff -u -r1.7 -r0 src/lib/libpthread/pthread_barrier_destroy.3 \ src/lib/libpthread/pthread_barrier_wait.3 \ src/lib/libpthread/pthread_cond_broadcast.3 \ src/lib/libpthread/pthread_rwlock_unlock.3 cvs rdiff -u -r1.9 -r0 src/lib/libpthread/pthread_barrier_init.3 \ src/lib/libpthread/pthread_rwlock_init.3 cvs rdiff -u -r1.4 -r0 src/lib/libpthread/pthread_cond_destroy.3 \ src/lib/libpthread/pthread_mutex_destroy.3 cvs rdiff -u -r1.10 -r0 src/lib/libpthread/pthread_cond_init.3 \ src/lib/libpthread/pthread_rwlock_rdlock.3 cvs rdiff -u -r1.15 -r0 src/lib/libpthread/pthread_cond_wait.3 cvs rdiff -u -r1.6 -r0 src/lib/libpthread/pthread_mutex_init.3 \ src/lib/libpthread/pthread_mutex_lock.3 \ src/lib/libpthread/pthread_rwlock_destroy.3 \ src/lib/libpthread/pthread_spin_destroy.3 cvs rdiff -u -r1.3 -r0 src/lib/libpthread/pthread_mutex_unlock.3 cvs rdiff -u -r1.8 -r0 src/lib/libpthread/pthread_rwlock_wrlock.3 \ src/lib/libpthread/pthread_spin_init.3 \ src/lib/libpthread/pthread_spin_lock.3 \ src/lib/libpthread/pthread_spin_unlock.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/distrib/sets/lists/comp/mi diff -u src/distrib/sets/lists/comp/mi:1.1480 src/distrib/sets/lists/comp/mi:1.1481 --- src/distrib/sets/lists/comp/mi:1.1480 Wed Jul 7 11:04:52 2010 +++ src/distrib/sets/lists/comp/mi Thu Jul 8 19:20:27 2010 @@ -1,4 +1,4 @@ -# $NetBSD: mi,v 1.1480 2010/07/07 11:04:52 jruoho Exp $ +# $NetBSD: mi,v 1.1481 2010/07/08 19:20:27 rmind Exp $ # # Note: don't delete entries from here - mark them as "obsolete" instead. # @@ -7588,6 +7588,7 @@ ./usr/share/man/cat3/pthread_attr_setstacksize.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_barierattr_destroy.0 comp-obsolete obsolete ./usr/share/man/cat3/pthread_barierattr_init.0 comp-obsolete obsolete +./usr/share/man/cat3/pthread_barrier.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_barrier_destroy.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_barrier_init.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_barrier_wait.0 comp-c-catman .cat @@ -7597,6 +7598,7 @@ ./usr/share/man/cat3/pthread_cancel.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_cleanup_pop.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_cleanup_push.0 comp-c-catman .cat +./usr/share/man/cat3/pthread_cond.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_cond_broadcast.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_cond_destroy.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_cond_init.0 comp-c-catman .cat @@ -7618,6 +7620,7 @@ ./usr/share/man/cat3/pthread_key_create.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_key_delete.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_kill.0 comp-c-catman .cat +./usr/share/man/cat3/pthread_mutex.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_mutex_destroy.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_mutex_init.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_mutex_lock.0 comp-c-catman .cat @@ -7630,6 +7633,7 @@ ./usr/share/man/cat3/pthread_mutexattr_settype.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_once.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_resume_np.0 comp-c-catman .cat +./usr/share/man/cat3/pthread_rwlock.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_rwlock_destroy.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_rwlock_init.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_rwlock_rdlock.0 comp-c-catman .cat @@ -7651,6 +7655,7 @@ ./usr/share/man/cat3/pthread_setschedparam.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_setspecific.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_sigmask.0 comp-c-catman .cat +./usr/share/man/cat3/pthread_spin.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_spin_destroy.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_spin_init.0 comp-c-catman .cat ./usr/share/man/cat3/pthread_spin_lock.0 comp-c-catman .cat @@ -13426,6 +13431,7 @@ ./usr/share/man/html3/pthread_attr_setstack.html comp-c-htmlman html ./usr/share/man/html3/pthread_attr_setstackaddr.html comp-c-htmlman html ./usr/share/man/html3/pthread_attr_setstacksize.html comp-c-htmlman html +./usr/share/man/html3/pthread_barrier.html comp-c-htmlman html ./usr/share/man/html3/pthread_barrier_destroy.html comp-c-htmlman html ./usr/share/man/html3/pthread_barrier_init.html comp-c-htmlman html ./usr/share/man/html3/pthread_barrier_wait.html comp-c-htmlman html @@ -13435,6 +13441,7 @@ ./usr/share/man/html3/pthread_cancel.html comp-c-htmlman html ./usr/share/man/html3/pthread_cleanup_pop.html comp-c-htmlman html ./usr/share/man/html3/pthread_cleanup_push.html comp-c-htmlman html +./usr/share/man/html3/pthread_cond.html comp-c-htmlman html ./usr/share/man/html3/pthread_cond_broadcast.html comp-c-htmlman html ./usr/share/man/html3/pthread_cond_destroy.html comp-c-htmlman html ./usr/share/man/html3/pthread_cond_init.html comp-c-htmlman html @@ -13456,6 +13463,7 @@ ./usr/share/man/html3/pthread_key_create.html comp-c-htmlman html ./usr/share/man/html3/pthread_key_delete.html comp-c-htmlman html ./usr/share/man/html3/pthread_kill.html comp-c-htmlman html +./usr/share/man/html3/pthread_mutex.html comp-c-htmlman html ./usr/share/man/html3/pthread_mutex_destroy.html comp-c-htmlman html ./usr/share/man/html3/pthread_mutex_init.html comp-c-htmlman html ./usr/share/man/html3/pthread_mutex_lock.html comp-c-htmlman html @@ -13468,6 +13476,7 @@ ./usr/share/man/html3/pthread_mutexattr_settype.html comp-c-htmlman html ./usr/share/man/html3/pthread_once.html comp-c-htmlman html ./usr/share/man/html3/pthread_resume_np.html comp-c-htmlman html +./usr/share/man/html3/pthread_rwlock.html comp-c-htmlman html ./usr/share/man/html3/pthread_rwlock_destroy.html comp-c-htmlman html ./usr/share/man/html3/pthread_rwlock_init.html comp-c-htmlman html ./usr/share/man/html3/pthread_rwlock_rdlock.html comp-c-htmlman html @@ -13489,6 +13498,7 @@ ./usr/share/man/html3/pthread_setschedparam.html comp-c-htmlman html ./usr/share/man/html3/pthread_setspecific.html comp-c-htmlman html ./usr/share/man/html3/pthread_sigmask.html comp-c-htmlman html +./usr/share/man/html3/pthread_spin.html comp-c-htmlman html ./usr/share/man/html3/pthread_spin_destroy.html comp-c-htmlman html ./usr/share/man/html3/pthread_spin_init.html comp-c-htmlman html ./usr/share/man/html3/pthread_spin_lock.html comp-c-htmlman html @@ -19262,6 +19272,7 @@ ./usr/share/man/man3/pthread_attr_setstacksize.3 comp-c-man .man ./usr/share/man/man3/pthread_barierattr_destroy.3 comp-obsolete obsolete ./usr/share/man/man3/pthread_barierattr_init.3 comp-obsolete obsolete +./usr/share/man/man3/pthread_barrier.3 comp-c-man .man ./usr/share/man/man3/pthread_barrier_destroy.3 comp-c-man .man ./usr/share/man/man3/pthread_barrier_init.3 comp-c-man .man ./usr/share/man/man3/pthread_barrier_wait.3 comp-c-man .man @@ -19271,6 +19282,7 @@ ./usr/share/man/man3/pthread_cancel.3 comp-c-man .man ./usr/share/man/man3/pthread_cleanup_pop.3 comp-c-man .man ./usr/share/man/man3/pthread_cleanup_push.3 comp-c-man .man +./usr/share/man/man3/pthread_cond.3 comp-c-man .man ./usr/share/man/man3/pthread_cond_broadcast.3 comp-c-man .man ./usr/share/man/man3/pthread_cond_destroy.3 comp-c-man .man ./usr/share/man/man3/pthread_cond_init.3 comp-c-man .man @@ -19292,6 +19304,7 @@ ./usr/share/man/man3/pthread_key_create.3 comp-c-man .man ./usr/share/man/man3/pthread_key_delete.3 comp-c-man .man ./usr/share/man/man3/pthread_kill.3 comp-c-man .man +./usr/share/man/man3/pthread_mutex.3 comp-c-man .man ./usr/share/man/man3/pthread_mutex_destroy.3 comp-c-man .man ./usr/share/man/man3/pthread_mutex_init.3 comp-c-man .man ./usr/share/man/man3/pthread_mutex_lock.3 comp-c-man .man @@ -19304,6 +19317,7 @@ ./usr/share/man/man3/pthread_mutexattr_settype.3 comp-c-man .man ./usr/share/man/man3/pthread_once.3 comp-c-man .man ./usr/share/man/man3/pthread_resume_np.3 comp-c-man .man +./usr/share/man/man3/pthread_rwlock.3 comp-c-man .man ./usr/share/man/man3/pthread_rwlock_destroy.3 comp-c-man .man ./usr/share/man/man3/pthread_rwlock_init.3 comp-c-man .man ./usr/share/man/man3/pthread_rwlock_rdlock.3 comp-c-man .man @@ -19325,6 +19339,7 @@ ./usr/share/man/man3/pthread_setschedparam.3 comp-c-man .man ./usr/share/man/man3/pthread_setspecific.3 comp-c-man .man ./usr/share/man/man3/pthread_sigmask.3 comp-c-man .man +./usr/share/man/man3/pthread_spin.3 comp-c-man .man ./usr/share/man/man3/pthread_spin_destroy.3 comp-c-man .man ./usr/share/man/man3/pthread_spin_init.3 comp-c-man .man ./usr/share/man/man3/pthread_spin_lock.3 comp-c-man .man Index: src/lib/libpthread/Makefile diff -u src/lib/libpthread/Makefile:1.65 src/lib/libpthread/Makefile:1.66 --- src/lib/libpthread/Makefile:1.65 Wed Jul 7 16:22:30 2010 +++ src/lib/libpthread/Makefile Thu Jul 8 19:20:16 2010 @@ -1,4 +1,4 @@ -# $NetBSD: Makefile,v 1.65 2010/07/07 16:22:30 jruoho Exp $ +# $NetBSD: Makefile,v 1.66 2010/07/08 19:20:16 rmind Exp $ # WARNS= 4 @@ -100,25 +100,19 @@ pthread_attr_getstack.3 \ pthread_attr_setcreatesuspend_np.3 \ pthread_attr_setname_np.3 \ - pthread_barrier_destroy.3 pthread_barrier_init.3 \ - pthread_barrier_wait.3 pthread_barrierattr.3 \ + pthread_barrier.3 pthread_barrierattr.3 \ pthread_cancel.3 pthread_cleanup_push.3 \ - pthread_cond_broadcast.3 pthread_cond_destroy.3 pthread_cond_init.3 \ - pthread_cond_wait.3 \ - pthread_condattr.3 pthread_create.3 pthread_detach.3 pthread_equal.3 \ + pthread_cond.3 pthread_condattr.3 \ + pthread_create.3 pthread_detach.3 pthread_equal.3 \ pthread_exit.3 \ pthread_getname_np.3 \ pthread_getspecific.3 pthread_join.3 \ pthread_key_create.3 pthread_key_delete.3 pthread_kill.3 \ - pthread_mutex_destroy.3 pthread_mutex_init.3 pthread_mutex_lock.3 \ - pthread_mutex_unlock.3 pthread_mutexattr.3 \ - pthread_once.3 pthread_rwlock_destroy.3 pthread_rwlock_init.3 \ - pthread_rwlock_rdlock.3 pthread_rwlock_unlock.3 \ - pthread_rwlock_wrlock.3 pthread_rwlockattr.3 \ + pthread_mutex.3 pthread_mutexattr.3 \ + pthread_once.3 pthread_rwlock.3 pthread_rwlockattr.3 \ pthread_schedparam.3 pthread_self.3 \ pthread_setname_np.3 \ - pthread_setspecific.3 pthread_sigmask.3 pthread_spin_destroy.3 \ - pthread_spin_init.3 pthread_spin_lock.3 pthread_spin_unlock.3 \ + pthread_setspecific.3 pthread_sigmask.3 pthread_spin.3 \ pthread_suspend_np.3 pthread_testcancel.3 MLINKS+= affinity.3 pthread_setaffinity_np.3 @@ -139,27 +133,58 @@ pthread_attr_getstack.3 pthread_attr_getstackaddr.3 \ pthread_attr_getstack.3 pthread_attr_setstackaddr.3 +MLINKS+= pthread_cleanup_push.3 pthread_cleanup_pop.3 + +MLINKS+= pthread_barrier.3 pthread_barrier_init.3 +MLINKS+= pthread_barrier.3 pthread_barrier_destroy.3 +MLINKS+= pthread_barrier.3 pthread_barrier_wait.3 + MLINKS+= pthread_barrierattr.3 pthread_barrierattr_init.3 MLINKS+= pthread_barrierattr.3 pthread_barrierattr_destroy.3 -MLINKS+= pthread_cleanup_push.3 pthread_cleanup_pop.3 -MLINKS+= pthread_cond_broadcast.3 pthread_cond_signal.3 -MLINKS+= pthread_cond_wait.3 pthread_cond_timedwait.3 + +MLINKS+= pthread_cond.3 pthread_cond_init.3 +MLINKS+= pthread_cond.3 pthread_cond_destroy.3 +MLINKS+= pthread_cond.3 pthread_cond_broadcast.3 +MLINKS+= pthread_cond.3 pthread_cond_wait.3 +MLINKS+= pthread_cond.3 pthread_cond_signal.3 +MLINKS+= pthread_cond.3 pthread_cond_timedwait.3 + MLINKS+= pthread_condattr.3 pthread_condattr_init.3 MLINKS+= pthread_condattr.3 pthread_condattr_destroy.3 -MLINKS+= pthread_mutex_lock.3 pthread_mutex_trylock.3 + +MLINKS+= pthread_mutex.3 pthread_mutex_init.3 +MLINKS+= pthread_mutex.3 pthread_mutex_destroy.3 +MLINKS+= pthread_mutex.3 pthread_mutex_lock.3 +MLINKS+= pthread_mutex.3 pthread_mutex_trylock.3 +MLINKS+= pthread_mutex.3 pthread_mutex_unlock.3 + MLINKS+= pthread_mutexattr.3 pthread_mutexattr_init.3 MLINKS+= pthread_mutexattr.3 pthread_mutexattr_destroy.3 MLINKS+= pthread_mutexattr.3 pthread_mutexattr_settype.3 MLINKS+= pthread_mutexattr.3 pthread_mutexattr_gettype.3 -MLINKS+= pthread_rwlock_rdlock.3 pthread_rwlock_timedrdlock.3 -MLINKS+= pthread_rwlock_rdlock.3 pthread_rwlock_tryrdlock.3 -MLINKS+= pthread_rwlock_wrlock.3 pthread_rwlock_timedwrlock.3 -MLINKS+= pthread_rwlock_wrlock.3 pthread_rwlock_trywrlock.3 + +MLINKS+= pthread_rwlock.3 pthread_rwlock_init.3 +MLINKS+= pthread_rwlock.3 pthread_rwlock_destroy.3 +MLINKS+= pthread_rwlock.3 pthread_rwlock_rdlock.3 +MLINKS+= pthread_rwlock.3 pthread_rwlock_wrlock.3 +MLINKS+= pthread_rwlock.3 pthread_rwlock_unlock.3 + +MLINKS+= pthread_rwlock.3 pthread_rwlock_timedrdlock.3 +MLINKS+= pthread_rwlock.3 pthread_rwlock_timedwrlock.3 +MLINKS+= pthread_rwlock.3 pthread_rwlock_tryrdlock.3 +MLINKS+= pthread_rwlock.3 pthread_rwlock_trywrlock.3 + MLINKS+= pthread_rwlockattr.3 pthread_rwlockattr_init.3 MLINKS+= pthread_rwlockattr.3 pthread_rwlockattr_destroy.3 + +MLINKS+= pthread_spin.3 pthread_spin_init.3 +MLINKS+= pthread_spin.3 pthread_spin_destroy.3 +MLINKS+= pthread_spin.3 pthread_spin_lock.3 +MLINKS+= pthread_spin.3 pthread_spin_trylock.3 +MLINKS+= pthread_spin.3 pthread_spin_unlock.3 + MLINKS+= pthread_schedparam.3 pthread_setschedparam.3 MLINKS+= pthread_schedparam.3 pthread_getschedparam.3 -MLINKS+= pthread_spin_lock.3 pthread_spin_trylock.3 MLINKS+= pthread_suspend_np.3 pthread_resume_np.3 MLINKS+= pthread_testcancel.3 pthread_setcancelstate.3 MLINKS+= pthread_testcancel.3 pthread_setcanceltype.3 Added files: Index: src/lib/libpthread/pthread_barrier.3 diff -u /dev/null src/lib/libpthread/pthread_barrier.3:1.1 --- /dev/null Thu Jul 8 19:20:34 2010 +++ src/lib/libpthread/pthread_barrier.3 Thu Jul 8 19:20:16 2010 @@ -0,0 +1,161 @@ +.\" $NetBSD: pthread_barrier.3,v 1.1 2010/07/08 19:20:16 rmind Exp $ +.\" +.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" ---------------------------------------------------------------------------- +.Dd July 8, 2010 +.Dt PTHREAD_BARRIER 3 +.Os +.Sh NAME +.Nm pthread_barrier +.Nd barrier interface +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_barrier_init "pthread_barrier_t * restrict barrier" \ +"const pthread_barrierattr_t * restrict attr" "unsigned int count" +.Ft int +.Fn pthread_barrier_destroy "pthread_barrier_t *barrier" +.Ft int +.Fn pthread_barrier_wait "pthread_barrier_t *barrier" +.\" ---------------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn pthread_barrier_init +function creates a new barrier, with attributes specified with +.Fa attr +and +.Fa count . +The +.Fa count +parameter indicates the number of threads which will participate in the barrier. +If +.Fa attr +is NULL the default attributes are used. +Barriers are most commonly used in the decomposition of parallel loops. +.Pp +.\" ----- +The +.Fn pthread_barrier_destroy +function causes the resources allocated to +.Fa barrier +to be released. +No threads should be blocked on +.Fa barrier . +.Pp +.\" ----- +The +.Fn pthread_barrier_wait +function causes the current thread to wait on the barrier specified. +Once as many threads as specified by the +.Fa count +parameter to the corresponding +.Fn pthread_barrier_init +call have called +.Fn pthread_barrier_wait , +all threads will wake up, return from their respective +.Fn pthread_barrier_wait +calls and continue execution. +.\" ---------------------------------------------------------------------------- +.Sh RETURN VALUES +If successful, +.Fn pthread_barrier_init +will return zero and put the new barrier id into +.Fa barrier , +otherwise an error number will be returned to indicate the error. +.Pp +.\" ----- +If successful, +.Fn pthread_barrier_destroy +will return zero. +Otherwise an error value will be returned. +.Pp +.\" ----- +If successful, +.Fn pthread_barrier_wait +will return zero for all waiting threads except for one. +One thread will receive status +.Dv PTHREAD_BARRIER_SERIAL_THREAD , +which is intended to indicate that this thread may be used to update +shared data. +It is the responsibility of this thread to insure the visibility +and atomicity of any updates to shared data with respect to the +other threads participating in the barrier. +In the case of failure, an error value will be returned. +.\" ---------------------------------------------------------------------------- +.Sh ERRORS +.Fn pthread_barrier_init +may fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacks the resources to initialize another barrier. +.It Bq Er EINVAL +The value specified by +.Fa count +is zero or +.Fa attr +is invalid. +.It Bq Er ENOMEM +Insufficient memory exists to initialize the barrier. +.It Bq Er EBUSY +The barrier structure has been initialized already. +.El +.Pp +.\" ----- +.Fn pthread_barrier_destroy +may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The +.Fa barrier +still has active threads associated with it. +.It Bq Er EINVAL +The value specified by +.Fa barrier +is invalid. +.El +.Pp +.\" ----- +.Fn pthread_barrier_wait +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa barrier +is invalid. +.El +.\" ---------------------------------------------------------------------------- +.Sh SEE ALSO +.Xr pthread 3 , +.Xr pthread_barrierattr 3 , +.Xr pthread_cond 3 +.Xr pthread_mutex 3 , +.Xr pthread_rwlock 3 , +.Xr pthread_spin 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . Index: src/lib/libpthread/pthread_cond.3 diff -u /dev/null src/lib/libpthread/pthread_cond.3:1.1 --- /dev/null Thu Jul 8 19:20:34 2010 +++ src/lib/libpthread/pthread_cond.3 Thu Jul 8 19:20:20 2010 @@ -0,0 +1,339 @@ +.\" $NetBSD: pthread_cond.3,v 1.1 2010/07/08 19:20:20 rmind Exp $ +.\" +.\" Copyright (c) 2002, 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1997 Brian Cully <sh...@kublai.com> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ---------------------------------------------------------------------------- +.Dd July 8, 2010 +.Dt PTHREAD_COND 3 +.Os +.Sh NAME +.Nm pthread_cond +.Nd condition variable interface +.Sh LIBRARY +.Lb libpthread +.\" ---------------------------------------------------------------------------- +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cond_init "pthread_cond_t * restrict cond" \ +"const pthread_condattr_t * restrict attr" +.Pp +.Va pthread_cond_t cond = Dv PTHREAD_COND_INITIALIZER; +.Ft int +.Fn pthread_cond_destroy "pthread_cond_t *cond" +.Ft int +.Fn pthread_cond_broadcast "pthread_cond_t *cond" +.Ft int +.Fn pthread_cond_signal "pthread_cond_t *cond" +.Ft int +.Fn pthread_cond_wait "pthread_cond_t * restrict cond" \ +"pthread_mutex_t * restrict mutex" +.Ft int +.Fn pthread_cond_timedwait "pthread_cond_t * restrict cond" \ +"pthread_mutex_t * restrict mutex" "const struct timespec * restrict abstime" +.\" ---------------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn pthread_cond_init +function creates a new condition variable, with attributes specified with +.Fa attr . +If +.Fa attr +is NULL the default attributes are used. +.Pp +Condition variables are intended to be used to communicate changes in +the state of data shared between threads. +Condition variables are always associated with a mutex to provide +synchronized access to the shared data. +A single predicate should always be associated with a +condition variable. +The predicate should identify a state of the +shared data that must be true before the thread proceeds. +.Pp +The macro +.Dv PTHREAD_COND_INITIALIZER +can be used to initialize a condition variable when it can be statically +allocated and the default attributes are appropriate. +The effect is similar to calling +.Fn pthread_cond_init +with +.Fa attr +specified as +.Dv NULL , +except that no error checking is done. +.Pp +.\" ----- +The +.Fn pthread_cond_destroy +function frees the resources allocated by the condition variable +.Fa cond . +.Pp +.\" ----- +The +.Fn pthread_cond_broadcast +function unblocks all threads waiting for the condition variable +.Fa cond . +If no threads are waiting on +.Fa cond , +the +.Fn pthread_cond_broadcast +function has no effect. +.Pp +The +.Fn pthread_cond_signal +function unblocks one thread waiting for the condition variable +.Fa cond . +If no threads are waiting on +.Fa cond , +the +.Fn pthread_cond_signal +function has no effect. +.Pp +When calling +.Fn pthread_cond_wait +and/or +.Fn pthread_cond_timedwait , +a temporary binding is established between the condition variable +.Fa cond +and a caller-supplied mutex. +.Pp +The same mutex must be held while calling +.Fn pthread_cond_broadcast +and +.Fn pthread_cond_signal . +Neither function enforces this requirement, but if the mutex is not +held the resulting behaviour is undefined. +.Pp +.\" ----- +The +.Fn pthread_cond_wait +function atomically blocks the current thread waiting on the condition +variable specified by +.Fa cond , +and unlocks the mutex specified by +.Fa mutex . +The waiting thread unblocks after another thread calls +.Xr pthread_cond_signal 3 , +or +.Xr pthread_cond_broadcast 3 +with the same condition variable. +The current thread holds the lock on +.Fa mutex +upon return from the +.Fn pthread_cond_wait +call. +.Pp +The +.Fn pthread_cond_timedwait +function atomically blocks the current thread waiting on the condition +variable specified by +.Fa cond , +and unlocks the mutex specified by +.Fa mutex . +The waiting thread unblocks after another thread calls +.Xr pthread_cond_signal 3 , +or +.Xr pthread_cond_broadcast 3 +with the same condition variable, or if the system time reaches the +time specified in +.Fa abstime , +represented as +.Em struct timespec +(see +.Xr timespec 3 ) . +.Pp +Note that a call to +.Fn pthread_cond_wait +or +.Fn pthread_cond_timedwait +may wake up spontaneously, without a call to +.Xr pthread_cond_signal 3 +or +.Xr pthread_cond_broadcast 3 . +The caller should prepare for this by invoking +.Fn pthread_cond_wait +or +.Fn pthread_cond_timedwait +within a predicate loop that tests whether the thread should proceed. +.Pp +When calling +.Fn pthread_cond_wait +or +.Fn pthread_cond_timedwait , +a temporary binding is established between the condition variable +.Fa cond +and the mutex +.Fa mutex . +.Pp +The same mutex must be held while calling +.Fn pthread_cond_broadcast +and +.Fn pthread_cond_signal +on +.Fa cond . +Additionally, the same mutex must be used for concurrent calls to +.Fn pthread_cond_wait +and +.Fn pthread_cond_timedwait . +Only when a condition variable is known to be quiescent may an application +change the mutex associated with it. +In this implementation, none of the functions enforce this requirement, but +if the mutex is not held or independent mutexes are used the resulting +behaviour is undefined. +.\" ---------------------------------------------------------------------------- +.Sh RETURN VALUES +If successful, the +.Fn pthread_cond_init +function will return zero and put the new condition variable id into +.Fa cond , +otherwise an error number will be returned to indicate the error. +.Pp +.\" ----- +If successful, the +.Fn pthread_cond_destroy , +.Fn pthread_cond_signal , +.Fn pthread_cond_broadcast , +.Fn pthread_cond_wait +and +.Fn pthread_cond_timedwait +will return zero, otherwise an error number will be returned to +indicate the error. +.\" ---------------------------------------------------------------------------- +.Sh ERRORS +.Fn pthread_cond_init +may fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacks the resources to initialize another condition variable. +.It Bq Er ENOMEM +The process cannot allocate enough memory to initialize another condition +variable. +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Pp +.\" ----- +.Fn pthread_cond_destroy +may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The variable +.Fa cond +is locked by another thread. +.It Bq Er EINVAL +The value specified by +.Fa cond +is invalid. +.El +.Pp +.\" ----- +.Fn pthread_cond_broadcast +and +.Fn pthread_cond_signal +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa cond +is invalid. +.El +.Pp +.\" ----- +.Fn pthread_cond_wait +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa cond +or the value specified by +.Fa mutex +is invalid. +.El +.Pp +.Fn pthread_cond_timedwait +may fail if: +.Bl -tag -width Er +.It Bq Er ETIMEDOUT +The system time has reached or exceeded the time specified in +.Fa abstime . +.It Bq Er EINVAL +The value specified by +.Fa cond , +.Fa mutex , +or +.Fa abstime +is invalid. +.El +.Pp +.Fn pthread_cond_wait +and +.Fn pthread_cond_timedwait +may fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The value specified by +.Fa mutex +is not locked in condition wait. +.El +.\" ---------------------------------------------------------------------------- +.Sh SEE ALSO +.Xr pthread 3 , +.Xr pthread_barrier 3 , +.Xr pthread_condattr 3 , +.Xr pthread_mutex 3 , +.Xr pthread_rwlock 3 , +.Xr pthread_spin 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . Index: src/lib/libpthread/pthread_mutex.3 diff -u /dev/null src/lib/libpthread/pthread_mutex.3:1.1 --- /dev/null Thu Jul 8 19:20:34 2010 +++ src/lib/libpthread/pthread_mutex.3 Thu Jul 8 19:20:23 2010 @@ -0,0 +1,224 @@ +.\" $NetBSD: pthread_mutex.3,v 1.1 2010/07/08 19:20:23 rmind Exp $ +.\" +.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1997 Brian Cully <sh...@kublai.com> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ---------------------------------------------------------------------------- +.Dd July 8, 2010 +.Dt PTHREAD_MUTEX 3 +.Os +.Sh NAME +.Nm pthread_mutex +.Nd mutex interface +.Sh LIBRARY +.Lb libpthread +.\" ---------------------------------------------------------------------------- +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutex_init "pthread_mutex_t * restrict mutex" \ +"const pthread_mutexattr_t * restrict attr" +.Pp +.Va pthread_mutex_t mutex = Dv PTHREAD_MUTEX_INITIALIZER; +.Ft int +.Fn pthread_mutex_destroy "pthread_mutex_t *mutex" +.Ft int +.Fn pthread_mutex_lock "pthread_mutex_t *mutex" +.Ft int +.Fn pthread_mutex_trylock "pthread_mutex_t *mutex" +.Ft int +.Fn pthread_mutex_unlock "pthread_mutex_t *mutex" +.\" ---------------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn pthread_mutex_init +function creates a new mutex, with attributes specified with +.Fa attr . +If +.Fa attr +is NULL the default attributes are used. +.Pp +The macro +.Dv PTHREAD_MUTEX_INITIALIZER +can be used to initialize a mutex when the default attributes are +appropriate and the mutex can be statically allocated. +The behavior is similar to +.Fn pthread_mutex_init +with +.Fa attr +specified as +.Dv NULL , +except that no error checking is done. +.Pp +.\" ----- +The +.Fn pthread_mutex_destroy +function frees the resources allocated for +.Fa mutex . +.Pp +.\" ----- +The +.Fn pthread_mutex_lock +function locks +.Fa mutex . +If the mutex is already locked, the calling thread will block until the +mutex becomes available. +.Pp +The +.Fn pthread_mutex_trylock +function locks +.Fa mutex . +If the mutex is already locked, +.Fn pthread_mutex_trylock +will not block waiting for the mutex, but will return an error condition. +.Pp +.\" ----- +If the current thread holds the lock on +.Fa mutex , +then the +.Fn pthread_mutex_unlock +function unlocks +.Fa mutex . +.\" ---------------------------------------------------------------------------- +.Sh RETURN VALUES +If successful, +.Fn pthread_mutex_init +will return zero and put the new mutex id into +.Fa mutex , +otherwise an error number will be returned to indicate the error. +.Pp +.\" ----- +If successful, +.Fn pthread_mutex_destroy , +.Fn pthread_mutex_lock , +.Fn pthread_mutex_trylock +and +.Fn pthread_mutex_unlock +will return zero, otherwise an error number will be returned to +indicate the error. +.Pp +.\" ---------------------------------------------------------------------------- +.Sh ERRORS +.Fn pthread_mutex_init +may fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacks the resources to initialize another mutex. +.It Bq Er ENOMEM +The process cannot allocate enough memory to initialize another mutex. +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Pp +.\" ----- +.Fn pthread_mutex_destroy +may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +.Fa Mutex +is locked by another thread. +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.El +.Pp +.\" ----- +.Fn pthread_mutex_lock +may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +A deadlock would occur if the thread blocked waiting for +.Fa mutex . +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.El +.Pp +.Fn pthread_mutex_trylock +may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +.Fa Mutex +is already locked. +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.El +.Pp +.\" ----- +.Fn pthread_mutex_unlock +may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.It Bq Er EPERM +The current thread does not hold a lock on +.Fa mutex . +.El +.\" ---------------------------------------------------------------------------- +.Sh SEE ALSO +.Xr pthread 3 , +.Xr pthread_barrier 3 , +.Xr pthread_cond 3 , +.Xr pthread_mutexattr 3 +.Xr pthread_rwlock 3 , +.Xr pthread_spin 3 +.\" ---------------------------------------------------------------------------- +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . Index: src/lib/libpthread/pthread_rwlock.3 diff -u /dev/null src/lib/libpthread/pthread_rwlock.3:1.1 --- /dev/null Thu Jul 8 19:20:34 2010 +++ src/lib/libpthread/pthread_rwlock.3 Thu Jul 8 19:20:24 2010 @@ -0,0 +1,343 @@ +.\" $NetBSD: pthread_rwlock.3,v 1.1 2010/07/08 19:20:24 rmind Exp $ +.\" +.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Copyright (c) 1998 Alex Nash +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" ---------------------------------------------------------------------------- +.Dd July 8, 2010 +.Dt PTHREAD_RWLOCK 3 +.Os +.Sh NAME +.Nm pthread_rwlock +.Nd read/write lock interface +.Sh LIBRARY +.Lb libpthread +.\" ---------------------------------------------------------------------------- +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlock_init "pthread_rwlock_t * restrict lock" \ +"const pthread_rwlockattr_t * restrict attr" +.Pp +.Va pthread_rwlock_t lock = Dv PTHREAD_RWLOCK_INITIALIZER; +.Ft int +.Fn pthread_rwlock_destroy "pthread_rwlock_t *lock" +.Ft int +.Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock" +.Ft int +.Fn pthread_rwlock_timedrdlock "pthread_rwlock_t * restrict lock" \ +"const struct timespec * restrict abstime" +.Ft int +.Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock" +.Ft int +.Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock" +.Ft int +.Fn pthread_rwlock_timedwrlock "pthread_rwlock_t * restrict lock" \ +"const struct timespec * restrict abstime" +.Ft int +.Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock" +.Ft int +.Fn pthread_rwlock_unlock "pthread_rwlock_t *lock" +.\" ---------------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn pthread_rwlock_init +function is used to initialize a read/write lock, with attributes +specified by +.Fa attr . +If +.Fa attr +is NULL, the default read/write lock attributes are used. +.Pp +The results of calling +.Fn pthread_rwlock_init +with an already initialized lock are undefined. +.Pp +The macro +.Dv PTHREAD_RWLOCK_INITIALIZER +can be used to initialize a read/write lock when the allocation can be done +statically, no error checking is required, and the default attributes are +appropriate. +The behavior is similar to calling +.Fn pthread_rwlock_init +with +.Fa attr +specified as +.Dv NULL . +.Pp +.\" ----- +The +.Fn pthread_rwlock_destroy +function is used to destroy a read/write lock previously created with +.Fn pthread_rwlock_init . +.Pp +.\" ----- +The +.Fn pthread_rwlock_rdlock +function acquires a read lock on +.Fa lock +provided that +.Fa lock +is not presently held for writing and no writer threads are +presently blocked on the lock. +If the read lock cannot be immediately acquired, the calling thread +blocks until it can acquire the lock. +.Pp +The +.Fn pthread_rwlock_timedrdlock +performs the same action, but will not wait beyond +.Fa abstime +to obtain the lock before returning. +.Pp +The +.Fn pthread_rwlock_tryrdlock +function performs the same action as +.Fn pthread_rwlock_rdlock , +but does not block if the lock cannot be immediately obtained (i.e., +the lock is held for writing or there are waiting writers). +.Pp +A thread may hold multiple concurrent read locks. +If so, +.Fn pthread_rwlock_unlock +must be called once for each lock obtained. +.Pp +The results of acquiring a read lock while the calling thread holds +a write lock are undefined. +.Pp +.\" ----- +The +.Fn pthread_rwlock_wrlock +function blocks until a write lock can be acquired against +.Fa lock . +.Pp +The +.Fn pthread_rwlock_timedwrlock +performs the same action, but will not wait beyond +.Fa abstime +to obtain the lock before returning. +.Pp +The +.Fn pthread_rwlock_trywrlock +function performs the same action as +.Fn pthread_rwlock_wrlock , +but does not block if the lock cannot be immediately obtained. +.Pp +The results are undefined if the calling thread already holds the +lock at the time the call is made. +.Pp +.\" ----- +The +.Fn pthread_rwlock_unlock +function is used to release the read/write lock previously obtained by +.Fn pthread_rwlock_rdlock , +.Fn pthread_rwlock_wrlock , +.Fn pthread_rwlock_tryrdlock , +or +.Fn pthread_rwlock_trywrlock . +.\" ---------------------------------------------------------------------------- +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlock_init +function will return zero. +Otherwise an error number will be returned to indicate the error. +.Pp +If successful, the +.Fn pthread_rwlock_destroy , +.Fn pthread_rwlock_rdlock , +.Fn pthread_rwlock_timedrdlock , +.Fn pthread_rwlock_tryrdlock , +.Fn pthread_rwlock_wrlock , +.Fn pthread_rwlock_timedwrlock , +.Fn pthread_rwlock_trywrlock , +and +.Fn pthread_rwlock_unlock +will return zero. +Otherwise an error number will be returned to indicate the error. +.Pp +The results are undefined if +.Fa lock +is not held by the calling thread. +.\" ---------------------------------------------------------------------------- +.Sh ERRORS +The +.Fn pthread_rwlock_init +function may fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacks the resources to initialize another read-write lock. +.It Bq Er ENOMEM +Insufficient memory exists to initialize the read-write lock. +.It Bq Er EBUSY +The system has detected an attempt to re-initialize the object +referenced by +.Fa lock , +a previously initialized but not yet destroyed read/write lock. +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Pp +.\" ----- +The +.Fn pthread_rwlock_destroy +function may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The system has detected an attempt to destroy the object referenced by +.Fa lock +while it is locked. +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.Pp +.\" ----- +The +.Fn pthread_rwlock_tryrdlock +function shall fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The lock could not be acquired because a writer holds the lock or +was blocked on it. +.El +.Pp +The +.Fn pthread_rwlock_timedrdlock +function shall fail if: +.Bl -tag -width Er +.It Bq Er ETIMEDOUT +The time specified by +.Fa abstime +was reached before the lock could be obtained. +.El +.Pp +The +.Fn pthread_rwlock_rdlock , +.Fn pthread_rwlock_timedrdlock , +and +.Fn pthread_rwlock_tryrdlock +functions may fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The lock could not be acquired because the maximum number of read locks +against +.Fa lock +has been exceeded. +.It Bq Er EDEADLK +The current thread already owns +.Fa lock +for writing. +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.Pp +.\" ----- +The +.Fn pthread_rwlock_trywrlock +function shall fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The calling thread is not able to acquire the lock without blocking. +.El +.Pp +The +.Fn pthread_rwlock_timedrdlock +function shall fail if: +.Bl -tag -width Er +.It Bq Er ETIMEDOUT +The time specified by +.Fa abstime +was reached before the lock could be obtained. +.El +.Pp +The +.Fn pthread_rwlock_wrlock , +.Fn pthread_rwlock_timedwrlock , +and +.Fn pthread_rwlock_trywrlock +functions may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +The calling thread already owns the read/write lock (for reading +or writing). +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.Pp +.\" ----- +The +.Fn pthread_rwlock_unlock +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.It Bq Er EPERM +The current thread does not own the read/write lock. +.El +.\" ---------------------------------------------------------------------------- +.Sh SEE ALSO +.Xr pthread 3 , +.Xr pthread_barrier 3 , +.Xr pthread_cond 3 +.Xr pthread_mutex 3 , +.Xr pthread_rwlockattr 3 , +.Xr pthread_spin 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . +.\" ---------------------------------------------------------------------------- +.Sh BUGS +The PTHREAD_PROCESS_SHARED attribute is not supported. Index: src/lib/libpthread/pthread_spin.3 diff -u /dev/null src/lib/libpthread/pthread_spin.3:1.1 --- /dev/null Thu Jul 8 19:20:34 2010 +++ src/lib/libpthread/pthread_spin.3 Thu Jul 8 19:20:25 2010 @@ -0,0 +1,226 @@ +.\" $NetBSD: pthread_spin.3,v 1.1 2010/07/08 19:20:25 rmind Exp $ +.\" +.\" Copyright (c) 2002, 2008, 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" ---------------------------------------------------------------------------- +.Dd July 8, 2010 +.Dt PTHREAD_SPIN 3 +.Os +.Sh NAME +.Nm pthread_spin +.Nd spin lock interface +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_spin_init "pthread_spinlock_t *lock" "int pshared" +.Ft int +.Fn pthread_spin_destroy "pthread_spinlock_t *lock" +.Ft int +.Fn pthread_spin_lock "pthread_spinlock_t *lock" +.Ft int +.Fn pthread_spin_trylock "pthread_spinlock_t *lock" +.Ft int +.Fn pthread_spin_unlock "pthread_spinlock_t *lock" +.\" ---------------------------------------------------------------------------- +.Sh DESCRIPTION +The +.Fn pthread_spin_init +function is used to initialize a spinlock. +The +.Fa pshared +parameter is currently unused and all spinlocks exhibit the +.Dv PTHREAD_PROCESS_SHARED +property. +.Pp +The results of calling +.Fn pthread_spin_init +with an already initialized lock are undefined. +.Pp +.\" ----- +The +.Fn pthread_spin_destroy +function is used to destroy a spin lock previously created with +.Fn pthread_spin_init . +.Pp +.\" ----- +The +.Fn pthread_spin_lock +function acquires a spin lock on +.Fa lock +provided that +.Fa lock +is not presently held. +If the lock cannot be +immediately acquired, the calling thread repeatedly retries until it can +acquire the lock. +.Pp +The +.Fn pthread_spin_trylock +function performs the same action, but does not block if the lock +cannot be immediately obtained (i.e., the lock is held). +.Pp +.\" ----- +The +.Fn pthread_spin_unlock +function is used to release the read/write lock previously obtained by +.Fn pthread_spin_lock +or +.Fn pthread_spin_trylock . +.\" ---------------------------------------------------------------------------- +.Sh RETURN VALUES +If successful, the +.Fn pthread_spin_init +function will return zero. +Otherwise an error number will be returned to indicate the error. +.Pp +.\" ----- +If successful, the +.Fn pthread_spin_destroy +function will return zero. +Otherwise an error number will be returned to indicate the error. +.Pp +.\" ----- +If successful, the +.Fn pthread_spin_lock +and +.Fn pthread_spin_trylock +functions will return zero. +Otherwise an error number will be returned to indicate the error. +.Pp +.\" ----- +If successful, the +.Fn pthread_spin_unlock +function will return zero. +Otherwise an error number will be returned to indicate the error. +.Pp +The results are undefined if +.Fa lock +is not held by the calling thread. +.\" ---------------------------------------------------------------------------- +.Sh ERRORS +The +.Fn pthread_spin_init +function shall fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory exists to initialize the lock. +.El +.Pp +The +.Fn pthread_spin_init +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa lock +parameter was NULL or the +.Fa pshared +parameter was neither +.Dv PTHREAD_PROCESS_SHARED +nor +.Dv PTHREAD_PROCESS_PRIVATE . +.El +.Pp +.\" ----- +The +.Fn pthread_spin_destroy +function may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The system has detected an attempt to destroy the object referenced by +.Fa lock +while it is locked. +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.Pp +.\" ----- +The +.Fn pthread_spin_trylock +function shall fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The lock could not be acquired because a writer holds the lock or +was blocked on it. +.El +.Pp +The +.Fn pthread_spin_lock +function may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +The current thread already owns +.Fa lock +for writing. +.El +.Pp +The +.Fn pthread_spin_lock +and +.Fn pthread_spin_trylock +functions may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.Pp +.\" ----- +The +.Fn pthread_spin_unlock +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.\" ---------------------------------------------------------------------------- +.Sh SEE ALSO +.Xr pthread 3 , +.Xr pthread_barrier 3 , +.Xr pthread_cond 3 +.Xr pthread_mutex 3 , +.Xr pthread_rwlock 3 , +.Xr pthread_spin 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2001 . +.\" ---------------------------------------------------------------------------- +.Sh CAVEATS +Applications using spinlocks are vulnerable to the effects of priority +inversion. +Applications using real-time threads +.Pq Dv SCHED_FIFO , +.Pq Dv SCHED_RR +should not use these interfaces. +Outside carefully controlled environments, priority inversion with spinlocks +can lead to system deadlock. +Mutexes are preferable in nearly every possible use case.