1.\" $NetBSD: pthread_barrier.3,v 1.4 2010/07/09 18:07:20 jruoho Exp $ 2.\" 3.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" ---------------------------------------------------------------------------- 28.Dd July 8, 2010 29.Dt PTHREAD_BARRIER 3 30.Os 31.Sh NAME 32.Nm pthread_barrier 33.Nd barrier interface 34.Sh LIBRARY 35.Lb libpthread 36.Sh SYNOPSIS 37.In pthread.h 38.Ft int 39.Fn pthread_barrier_init "pthread_barrier_t * restrict barrier" \ 40"const pthread_barrierattr_t * restrict attr" "unsigned int count" 41.Ft int 42.Fn pthread_barrier_destroy "pthread_barrier_t *barrier" 43.Ft int 44.Fn pthread_barrier_wait "pthread_barrier_t *barrier" 45.\" ---------------------------------------------------------------------------- 46.Sh DESCRIPTION 47The 48.Fn pthread_barrier_init 49function creates a new barrier with attributes 50.Fa attr 51and 52.Fa count . 53The 54.Fa count 55parameter indicates the number of threads 56which will participate in the barrier. 57The 58.Xr pthread_barrierattr_init 3 59function may be used to specify the attributes supplied in 60.Fa attr . 61If 62.Fa attr 63is 64.Dv NULL , 65the default attributes are used. 66Barriers are most commonly used in the decomposition of parallel loops. 67.Pp 68.\" ----- 69The 70.Fn pthread_barrier_destroy 71function causes the resources allocated to 72.Fa barrier 73to be released. 74No threads should be blocked on 75.Fa barrier . 76.Pp 77.\" ----- 78The 79.Fn pthread_barrier_wait 80function causes the current thread to wait on the barrier specified. 81Once as many threads as specified by the 82.Fa count 83parameter to the corresponding 84.Fn pthread_barrier_init 85call have called 86.Fn pthread_barrier_wait , 87all threads will wake up, return from their respective 88.Fn pthread_barrier_wait 89calls and continue execution. 90.\" ---------------------------------------------------------------------------- 91.Sh RETURN VALUES 92If successful, 93.Fn pthread_barrier_init 94will return zero and put the new barrier id into 95.Fa barrier , 96otherwise an error number will be returned to indicate the error. 97.Pp 98.\" ----- 99If successful, 100.Fn pthread_barrier_destroy 101will return zero. 102Otherwise an error value will be returned. 103.Pp 104.\" ----- 105If successful, 106.Fn pthread_barrier_wait 107will return zero for all waiting threads except for one. 108One thread will receive status 109.Dv PTHREAD_BARRIER_SERIAL_THREAD , 110which is intended to indicate that this thread may be used to update 111shared data. 112It is the responsibility of this thread to insure the visibility 113and atomicity of any updates to shared data with respect to the 114other threads participating in the barrier. 115In the case of failure, an error value will be returned. 116.\" ---------------------------------------------------------------------------- 117.Sh ERRORS 118The 119.Fn pthread_barrier_init 120function may fail if: 121.Bl -tag -width Er 122.It Bq Er EINVAL 123The value specified by 124.Fa count 125is zero or 126.Fa attr 127is invalid. 128.El 129.Pp 130.\" ----- 131The 132.Fn pthread_barrier_destroy 133function may fail if: 134.Bl -tag -width Er 135.It Bq Er EBUSY 136The 137.Fa barrier 138still has active threads associated with it. 139.It Bq Er EINVAL 140The value specified by 141.Fa barrier 142is invalid. 143.El 144.Pp 145.\" ----- 146The 147.Fn pthread_barrier_wait 148function may fail if: 149.Bl -tag -width Er 150.It Bq Er EINVAL 151The value specified by 152.Fa barrier 153is invalid. 154.El 155.\" --------------------------------------------------------------------------- 156.Sh SEE ALSO 157.Xr pthread_barrierattr 3 , 158.Xr pthread_cond 3 , 159.Xr pthread_mutex 3 160.Sh STANDARDS 161These functions conform to 162.St -p1003.1-2001 . 163