1.\" Copyright (c) 2004 Michael Telahun Makonnen 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd February 19, 2004 28.Dt PTHREAD_BARRIER 3 29.Os 30.Sh NAME 31.Nm pthread_barrier_destroy , pthread_barrier_init , pthread_barrier_wait 32.Nd "destroy, initialize or wait on a barrier object" 33.Sh LIBRARY 34.Lb libpthread 35.Lb libthr 36.Sh SYNOPSIS 37.In pthread.h 38.Ft int 39.Fn pthread_barrier_destroy "pthread_barrier_t *barrier" 40.Ft int 41.Fn pthread_barrier_init "pthread_barrier_t *barrier" "const pthread_barrierattr_t *attr" "unsigned count" 42.Ft int 43.Fn pthread_barrier_wait "pthread_barrier_t *barrier" 44.Sh DESCRIPTION 45The 46.Fn pthread_barrier_init 47function will initialize 48.Fa barrier 49with attributes specified in 50.Fa attr , 51or if it is 52.Dv NULL , 53with default attributes. 54The number of threads that must call 55.Fn pthread_barrier_wait 56before any of the waiting threads can be 57released is specified by 58.Fa count . 59The 60.Fn pthread_barrier_destroy 61function will destroy 62.Fa barrier 63and release any resources that may have been allocated on its behalf. 64.Pp 65The 66.Fn pthread_barrier_wait 67function will synchronize calling threads at 68.Fa barrier . 69The threads will be blocked from 70making further progress until 71a sufficient number of threads calls this function. 72The number of threads that must call it before 73any of them will be released is determined by the 74.Fa count 75argument to 76.Fn pthread_barrier_init . 77Once the threads have been released the barrier will be reset. 78.Sh IMPLEMENTATION NOTES 79In both 80.Lb libpthread 81and 82.Lb libthr 83the 84.Dv PTHREAD_BARRIER_SERIAL_THREAD 85return value will 86always be returned by the last thread to reach the barrier. 87.Sh RETURN VALUES 88If successful, 89both 90.Fn pthread_barrier_destroy 91and 92.Fn pthread_barrier_init 93will return zero. 94Otherwise, an error number will be returned to indicate the error. 95If the call to 96.Fn pthread_barrier_wait 97is successful, all but one of the threads will return zero. 98That one thread will return 99.Dv PTHREAD_BARRIER_SERIAL_THREAD . 100Otherwise, an error number will be returned to indicate the error. 101.Pp 102None of these functions will return 103.Er EINTR . 104.Sh ERRORS 105The 106.Fn pthread_barrier_destroy 107function will fail if: 108.Bl -tag -width Er 109.It Bq Er EBUSY 110An attempt was made to destroy 111.Fa barrier 112while it was in use. 113.El 114.Pp 115The 116.Fn pthread_barrier_destroy 117and 118.Fn pthread_barrier_wait 119functions may fail if: 120.Bl -tag -width Er 121.It Bq Er EINVAL 122The value specified by 123.Fa barrier 124is invalid. 125.El 126.Pp 127The 128.Fn pthread_barrier_init 129function will fail if: 130.Bl -tag -width Er 131.It Bq Er EAGAIN 132The system lacks resources, 133other than memory, 134to initialize 135.Fa barrier . 136.It Bq Er EINVAL 137The 138.Fa count 139argument is less than 1. 140.It Bq Er ENOMEM 141Insufficient memory to initialize 142.Fa barrier . 143.El 144.Sh SEE ALSO 145.Xr pthread_barrierattr 3 146.Sh HISTORY 147The 148.Fn pthread_barrier_destroy , 149.Fn pthread_barrier_init 150and 151.Fn pthread_barrier_wait 152functions first appeared in 153.Lb libpthread 154in 155.Fx 5.2 , 156and in 157.Lb libthr 158in 159.Fx 5.3 . 160