share/man/man3/pthread_barrier_destroy.3

   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 August 17, 2018
  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 .Sh SYNOPSIS
  36 .In pthread.h
  37 .Ft int
  38 .Fn pthread_barrier_destroy "pthread_barrier_t *barrier"
  39 .Ft int
  40 .Fn pthread_barrier_init "pthread_barrier_t *restrict barrier" "const pthread_barrierattr_t *attr" "unsigned count"
  41 .Ft int
  42 .Fn pthread_barrier_wait "pthread_barrier_t *barrier"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn pthread_barrier_init
  46 function will initialize
  47 .Fa barrier
  48 with attributes specified in
  49 .Fa attr ,
  50 or if it is
  51 .Dv NULL ,
  52 with default attributes.
  53 The number of threads that must call
  54 .Fn pthread_barrier_wait
  55 before any of the waiting threads can be
  56 released is specified by
  57 .Fa count .
  58 The
  59 .Fn pthread_barrier_destroy
  60 function will destroy
  61 .Fa barrier
  62 and release any resources that may have been allocated on its behalf.
  63 .Pp
  64 The
  65 .Fn pthread_barrier_wait
  66 function will synchronize calling threads at
  67 .Fa barrier .
  68 The threads will be blocked from
  69 making further progress until
  70 a sufficient number of threads calls this function.
  71 The number of threads that must call it before
  72 any of them will be released is determined by the
  73 .Fa count
  74 argument to
  75 .Fn pthread_barrier_init .
  76 Once the threads have been released the barrier will be reset.
  77 .Sh IMPLEMENTATION NOTES
  78 In
  79 .Lb libthr
  80 the
  81 .Dv PTHREAD_BARRIER_SERIAL_THREAD
  82 return value will
  83 always be returned by the last thread to reach the barrier.
  84 .Sh RETURN VALUES
  85 If successful,
  86 both
  87 .Fn pthread_barrier_destroy
  88 and
  89 .Fn pthread_barrier_init
  90 will return zero.
  91 Otherwise, an error number will be returned to indicate the error.
  92 If the call to
  93 .Fn pthread_barrier_wait
  94 is successful, all but one of the threads will return zero.
  95 That one thread will return
  96 .Dv PTHREAD_BARRIER_SERIAL_THREAD .
  97 Otherwise, an error number will be returned to indicate the error.
  98 .Pp
  99 None of these functions will return
 100 .Er EINTR .
 101 .Sh ERRORS
 102 The
 103 .Fn pthread_barrier_destroy
 104 function will fail if:
 105 .Bl -tag -width Er
 106 .It Bq Er EBUSY
 107 An attempt was made to destroy
 108 .Fa barrier
 109 while it was in use.
 110 .El
 111 .Pp
 112 The
 113 .Fn pthread_barrier_destroy
 114 and
 115 .Fn pthread_barrier_wait
 116 functions may fail if:
 117 .Bl -tag -width Er
 118 .It Bq Er EINVAL
 119 The value specified by
 120 .Fa barrier
 121 is invalid.
 122 .El
 123 .Pp
 124 The
 125 .Fn pthread_barrier_init
 126 function will fail if:
 127 .Bl -tag -width Er
 128 .It Bq Er EAGAIN
 129 The system lacks resources,
 130 other than memory,
 131 to initialize
 132 .Fa barrier .
 133 .It Bq Er EINVAL
 134 The
 135 .Fa count
 136 argument is less than 1.
 137 .It Bq Er ENOMEM
 138 Insufficient memory to initialize
 139 .Fa barrier .
 140 .El
 141 .Sh SEE ALSO
 142 .Xr pthread_barrierattr 3
 143 .Sh HISTORY
 144 The
 145 .Fn pthread_barrier_destroy ,
 146 .Fn pthread_barrier_init
 147 and
 148 .Fn pthread_barrier_wait
 149 functions first appeared in
 150 .Lb libkse
 151 in
 152 .Fx 5.2 ,
 153 and in
 154 .Lb libthr
 155 in
 156 .Fx 5.3 .