dep/ACE_wrappers/ace/Barrier.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Barrier.h
   6  *
   7  *  $Id: Barrier.h 80826 2008-03-04 14:51:23Z wotte $
   8  *
   9  *   Moved from Synch.h.
  10  *
  11  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
  12  */
  13 //==========================================================================
  14
  15 #ifndef ACE_BARRIER_H
  16 #define ACE_BARRIER_H
  17 #include /**/ "ace/pre.h"
  18
  19 #include /**/ "ace/ACE_export.h"
  20
  21 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  22 # pragma once
  23 #endif /* ACE_LACKS_PRAGMA_ONCE */
  24
  25 #include /**/ "ace/config-all.h"
  26
  27 // ACE platform supports some form of threading.
  28 #if !defined (ACE_HAS_THREADS)
  29
  30 #include "ace/OS_NS_errno.h"
  31
  32 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  33
  34 /**
  35  * @class ACE_Barrier
  36  *
  37  * @brief This is a no-op to make ACE "syntactically consistent."
  38  */
  39 class ACE_Export ACE_Barrier
  40 {
  41 public:
  42   ACE_Barrier (unsigned int, const ACE_TCHAR * = 0, void * = 0) {}
  43   ~ACE_Barrier (void) {}
  44   int wait (void) { ACE_NOTSUP_RETURN (-1); }
  45   void dump (void) const {}
  46 };
  47
  48 ACE_END_VERSIONED_NAMESPACE_DECL
  49
  50 #else /* ACE_HAS_THREADS */
  51
  52 #include "ace/Condition_Thread_Mutex.h"
  53
  54 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  55
  56 struct ACE_Export ACE_Sub_Barrier
  57 {
  58   // = Initialization.
  59   ACE_Sub_Barrier (unsigned int count,
  60                    ACE_Thread_Mutex &lock,
  61                    const ACE_TCHAR *name = 0,
  62                    void *arg = 0);
  63
  64   ~ACE_Sub_Barrier (void);
  65
  66   /// True if this generation of the barrier is done.
  67   ACE_Condition_Thread_Mutex barrier_finished_;
  68
  69   /// Number of threads that are still running.
  70   int running_threads_;
  71
  72   /// Dump the state of an object.
  73   void dump (void) const;
  74
  75   /// Declare the dynamic allocation hooks.
  76   ACE_ALLOC_HOOK_DECLARE;
  77 };
  78
  79 /**
  80  * @class ACE_Barrier
  81  *
  82  * @brief Implements "barrier synchronization".
  83  *
  84  * This class allows <count> number of threads to synchronize
  85  * their completion of (one round of) a task, which is known as
  86  * "barrier synchronization".   After all the threads call <wait()>
  87  * on the barrier they are all atomically released and can begin a new
  88  * round.
  89  *
  90  * This implementation uses a "sub-barrier generation numbering"
  91  * scheme to avoid overhead and to ensure that all threads wait to
  92  * leave the barrier correct.  This code is based on an article from
  93  * SunOpsis Vol. 4, No. 1 by Richard Marejka
  94  * (Richard.Marejka@canada.sun.com).
  95  */
  96 class ACE_Export ACE_Barrier
  97 {
  98 public:
  99   /// Initialize the barrier to synchronize @a count threads.
 100   ACE_Barrier (unsigned int count,
 101                const ACE_TCHAR *name = 0,
 102                void *arg = 0);
 103
 104   /// Default dtor.
 105   ~ACE_Barrier (void);
 106
 107   /// Block the caller until all @c count threads have called @c wait and
 108   /// then allow all the caller threads to continue in parallel.
 109   ///
 110   /// @retval 0 after successfully waiting for all threads to wait.
 111   /// @retval -1 if an error occurs or the barrier is shut
 112   /// down (@sa shutdown ()).
 113   int wait (void);
 114
 115   /// Shut the barrier down, aborting the wait of all waiting threads.
 116   /// Any threads waiting on the barrier when it is shut down will return with
 117   /// value -1, errno ESHUTDOWN.
 118   ///
 119   /// @retval 0 for success, -1 if already shut down.
 120   ///
 121   /// @since ACE beta 5.4.9.
 122   int shutdown (void);
 123
 124   /// Dump the state of an object.
 125   void dump (void) const;
 126
 127   /// Declare the dynamic allocation hooks.
 128   ACE_ALLOC_HOOK_DECLARE;
 129
 130 protected:
 131   /// Serialize access to the barrier state.
 132   ACE_Thread_Mutex lock_;
 133
 134   /// Either 0 or 1, depending on whether we are the first generation
 135   /// of waiters or the next generation of waiters.
 136   int current_generation_;
 137
 138   /// Total number of threads that can be waiting at any one time.
 139   int count_;
 140
 141   /**
 142    * We keep two @c sub_barriers, one for the first "generation" of
 143    * waiters, and one for the next "generation" of waiters.  This
 144    * efficiently solves the problem of what to do if all the first
 145    * generation waiters don't leave the barrier before one of the
 146    * threads calls wait() again (i.e., starts up the next generation
 147    * barrier).
 148    */
 149   ACE_Sub_Barrier sub_barrier_1_;
 150   ACE_Sub_Barrier sub_barrier_2_;
 151   ACE_Sub_Barrier *sub_barrier_[2];
 152
 153 private:
 154   // = Prevent assignment and initialization.
 155   void operator= (const ACE_Barrier &);
 156   ACE_Barrier (const ACE_Barrier &);
 157 };
 158
 159 #if 0
 160 /**
 161  * @class ACE_Process_Barrier
 162  *
 163  * @brief Implements "barrier synchronization" using ACE_Process_Mutexes!
 164  *
 165  * This class is just a simple wrapper for ACE_Barrier that
 166  * selects the USYNC_PROCESS variant for the locks.
 167  */
 168 class ACE_Export ACE_Process_Barrier : public ACE_Barrier
 169 {
 170 public:
 171   /// Create a Process_Barrier, passing in the optional @a name.
 172   ACE_Process_Barrier (unsigned int count, const ACE_TCHAR *name = 0);
 173
 174   /// Dump the state of an object.
 175   void dump (void) const;
 176
 177   /// Declare the dynamic allocation hooks.
 178   ACE_ALLOC_HOOK_DECLARE;
 179 };
 180 #endif /* 0 */
 181
 182 /**
 183  * @class ACE_Thread_Barrier
 184  *
 185  * @brief Implements "barrier synchronization" using ACE_Thread_Mutexes!
 186  *
 187  * This class is just a simple wrapper for ACE_Barrier that
 188  * selects the USYNC_THREAD variant for the locks.
 189  */
 190 class ACE_Export ACE_Thread_Barrier : public ACE_Barrier
 191 {
 192 public:
 193   /// Create a Thread_Barrier, passing in the optional @a name.
 194   ACE_Thread_Barrier (unsigned int count, const ACE_TCHAR *name = 0);
 195
 196   /// Default dtor.
 197   ~ACE_Thread_Barrier (void);
 198
 199   /// Dump the state of an object.
 200   void dump (void) const;
 201
 202   /// Declare the dynamic allocation hooks.
 203   ACE_ALLOC_HOOK_DECLARE;
 204 };
 205
 206 ACE_END_VERSIONED_NAMESPACE_DECL
 207
 208 #if defined (__ACE_INLINE__)
 209 #include "ace/Barrier.inl"
 210 #endif /* __ACE_INLINE__ */
 211
 212 #endif /* !ACE_HAS_THREADS */
 213
 214 #include /**/ "ace/post.h"
 215 #endif /* ACE_BARRIER_H */