1.\"	$OpenBSD: pthread_barrier_init.3,v 1.5 2022/03/31 17:27:17 naddy Exp $
2.\"
3.\" Copyright (c) 2012 Paul Irofti <paul@irofti.net>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.\"
18.Dd $Mdocdate: March 31 2022 $
19.Dt PTHREAD_BARRIER_INIT 3
20.Os
21.Sh NAME
22.Nm pthread_barrier_init ,
23.Nm pthread_barrier_destroy
24.Nd initialize and destroy a barrier object
25.Sh SYNOPSIS
26.In pthread.h
27.Ft int
28.Fn pthread_barrier_init "pthread_barrier_t *barrier" "pthread_barrierattr_t *attr" "unsigned int count"
29.Ft int
30.Fn pthread_barrier_destroy "pthread_barrier_t *barrier"
31.Sh DESCRIPTION
32The
33.Fn pthread_barrier_init
34function creates a new barrier object, with attributes specified with
35.Fa attr
36and with a threshold specified with
37.Fa count .
38If
39.Fa attr
40is
41.Dv NULL ,
42the default attributes are used.
43The
44.Fa count
45argument is later used by the
46.Fn pthread_barrier_wait
47function to check if the required number of threads reached the barrier.
48.Pp
49The
50.Fn pthread_barrier_destroy
51function frees the resources allocated for
52.Fa barrier .
53.Sh RETURN VALUES
54If successful,
55.Fn pthread_barrier_init
56and
57.Fn pthread_barrier_destroy
58return zero;
59otherwise an error number is returned to indicate the error.
60.Sh ERRORS
61.Fn pthread_barrier_init
62will fail if:
63.Bl -tag -width Er
64.It Bq Er EINVAL
65The value specified by
66.Fa barrier
67or
68.Fa attr
69is invalid.
70.It Bq Er ENOMEM
71The process cannot allocate enough memory to create another barrier object.
72.It Bq Er ENOTSUP
73The attributes specified by
74.Fa attr
75are not supported by the current implementation.
76.El
77.Pp
78.Fn pthread_barrier_destroy
79will fail if:
80.Bl -tag -width Er
81.It Bq Er EINVAL
82The value specified by
83.Fa barrier
84is invalid.
85.It Bq Er EBUSY
86There are still threads waiting on the barrier.
87.El
88.Sh SEE ALSO
89.Xr pthread_barrier_wait 3 ,
90.Xr pthread_barrierattr_getpshared 3 ,
91.Xr pthread_barrierattr_init 3
92.Sh STANDARDS
93.Fn pthread_barrier_init
94and
95.Fn pthread_barrier_destroy
96conform to
97.St -p1003.1-2008 .
98.Sh BUGS
99Currently only private barriers are supported and the pshared attribute is
100always set that way.
101Any attempts to change that value will trigger
102.Er ENOTSUP .
103