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