ACE/ace/Barrier.h

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