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