1.\" $NetBSD: pthread_barrier.3,v 1.8 2017/10/22 16:15:02 abhinav 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 October 22, 2017 29.Dt PTHREAD_BARRIER 3 30.Os 31.Sh NAME 32.Nm pthread_barrier , 33.Nm pthread_barrier_init , 34.Nm pthread_barrier_destroy , 35.Nm pthread_barrier_wait 36.Nd barrier interface 37.Sh LIBRARY 38.Lb libpthread 39.Sh SYNOPSIS 40.In pthread.h 41.Ft int 42.Fn pthread_barrier_init "pthread_barrier_t * restrict barrier" \ 43"const pthread_barrierattr_t * restrict attr" "unsigned int count" 44.Ft int 45.Fn pthread_barrier_destroy "pthread_barrier_t *barrier" 46.Ft int 47.Fn pthread_barrier_wait "pthread_barrier_t *barrier" 48.\" ---------------------------------------------------------------------------- 49.Sh DESCRIPTION 50The 51.Fn pthread_barrier_init 52function creates a new barrier with attributes 53.Fa attr 54and 55.Fa count . 56The 57.Fa count 58parameter indicates the number of threads 59which will participate in the barrier. 60The 61.Xr pthread_barrierattr_init 3 62function may be used to specify the attributes supplied in 63.Fa attr . 64If 65.Fa attr 66is 67.Dv NULL , 68the default attributes are used. 69Barriers are most commonly used in the decomposition of parallel loops. 70.Pp 71.\" ----- 72The 73.Fn pthread_barrier_destroy 74function causes the resources allocated to 75.Fa barrier 76to be released. 77No threads should be blocked on 78.Fa barrier . 79.Pp 80.\" ----- 81The 82.Fn pthread_barrier_wait 83function causes the current thread to wait on the barrier specified. 84Once as many threads as specified by the 85.Fa count 86parameter to the corresponding 87.Fn pthread_barrier_init 88call have called 89.Fn pthread_barrier_wait , 90all threads will wake up, return from their respective 91.Fn pthread_barrier_wait 92calls and continue execution. 93.\" ----- 94.\" ---------------------------------------------------------------------------- 95.Sh RETURN VALUES 96If successful, 97.Fn pthread_barrier_init 98will return zero and put the new barrier id into 99.Fa barrier , 100otherwise an error number will be returned to indicate the error. 101.Pp 102.\" ----- 103If successful, 104.Fn pthread_barrier_destroy 105will return zero. 106Otherwise an error value will be returned. 107.Pp 108.\" ----- 109If successful, 110.Fn pthread_barrier_wait 111will return zero for all waiting threads except for one. 112One thread will receive status 113.Dv PTHREAD_BARRIER_SERIAL_THREAD , 114which is intended to indicate that this thread may be used to update 115shared data. 116It is the responsibility of this thread to insure the visibility 117and atomicity of any updates to shared data with respect to the 118other threads participating in the barrier. 119In the case of failure, an error value will be returned. 120.\" ---------------------------------------------------------------------------- 121.Sh ERRORS 122The 123.Fn pthread_barrier_init 124function may fail if: 125.Bl -tag -width Er 126.It Bq Er EINVAL 127The value specified by 128.Fa count 129is zero or 130.Fa attr 131is invalid. 132.El 133.Pp 134.\" ----- 135The 136.Fn pthread_barrier_destroy 137function may fail if: 138.Bl -tag -width Er 139.It Bq Er EBUSY 140The 141.Fa barrier 142still has active threads associated with it. 143.It Bq Er EINVAL 144The value specified by 145.Fa barrier 146is invalid. 147.El 148.Pp 149.\" ----- 150The 151.Fn pthread_barrier_wait 152function may fail if: 153.Bl -tag -width Er 154.It Bq Er EINVAL 155The value specified by 156.Fa barrier 157is invalid. 158.El 159.\" --------------------------------------------------------------------------- 160.Sh SEE ALSO 161.Xr pthread_barrierattr 3 , 162.Xr pthread_cond 3 , 163.Xr pthread_mutex 3 164.Sh STANDARDS 165These functions conform to 166.St -p1003.1-2001 . 167