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 .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 *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 both
  79 .Lb libkse
  80 and
  81 .Lb libthr
  82 the
  83 .Dv PTHREAD_BARRIER_SERIAL_THREAD
  84 return value will
  85 always be returned by the last thread to reach the barrier.
  86 .Sh RETURN VALUES
  87 If successful,
  88 both
  89 .Fn pthread_barrier_destroy
  90 and
  91 .Fn pthread_barrier_init
  92 will return zero.
  93 Otherwise, an error number will be returned to indicate the error.
  94 If the call to
  95 .Fn pthread_barrier_wait
  96 is successful, all but one of the threads will return zero.
  97 That one thread will return
  98 .Dv PTHREAD_BARRIER_SERIAL_THREAD .
  99 Otherwise, an error number will be returned to indicate the error.
 100 .Pp
 101 None of these functions will return
 102 .Er EINTR .
 103 .Sh ERRORS
 104 The
 105 .Fn pthread_barrier_destroy
 106 function will fail if:
 107 .Bl -tag -width Er
 108 .It Bq Er EBUSY
 109 An attempt was made to destroy
 110 .Fa barrier
 111 while it was in use.
 112 .El
 113 .Pp
 114 The
 115 .Fn pthread_barrier_destroy
 116 and
 117 .Fn pthread_barrier_wait
 118 functions may fail if:
 119 .Bl -tag -width Er
 120 .It Bq Er EINVAL
 121 The value specified by
 122 .Fa barrier
 123 is invalid.
 124 .El
 125 .Pp
 126 The
 127 .Fn pthread_barrier_init
 128 function will fail if:
 129 .Bl -tag -width Er
 130 .It Bq Er EAGAIN
 131 The system lacks resources,
 132 other than memory,
 133 to initialize
 134 .Fa barrier .
 135 .It Bq Er EINVAL
 136 The
 137 .Fa count
 138 argument is less than 1.
 139 .It Bq Er ENOMEM
 140 Insufficient memory to initialize
 141 .Fa barrier .
 142 .El
 143 .Sh SEE ALSO
 144 .Xr pthread_barrierattr 3
 145 .Sh HISTORY
 146 The
 147 .Fn pthread_barrier_destroy ,
 148 .Fn pthread_barrier_init
 149 and
 150 .Fn pthread_barrier_wait
 151 functions first appeared in
 152 .Lb libkse
 153 in
 154 .Fx 5.2 ,
 155 and in
 156 .Lb libthr
 157 in
 158 .Fx 5.3 .