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