lib/libpthread/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: src/share/man/man3/pthread_barrier_destroy.3,v 1.6 2007/10/22 10:08:00 ru Exp $
  26 .\"
  27 .Dd July 10, 2009
  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 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