absl/synchronization/barrier.h

0001 // Copyright 2017 The Abseil Authors.
0002 //
0003 // Licensed under the Apache License, Version 2.0 (the "License");
0004 // you may not use this file except in compliance with the License.
0005 // You may obtain a copy of the License at
0006 //
0007 //      https://www.apache.org/licenses/LICENSE-2.0
0008 //
0009 // Unless required by applicable law or agreed to in writing, software
0010 // distributed under the License is distributed on an "AS IS" BASIS,
0011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0012 // See the License for the specific language governing permissions and
0013 // limitations under the License.
0014 //
0015 // -----------------------------------------------------------------------------
0016 // barrier.h
0017 // -----------------------------------------------------------------------------
0018
0019 #ifndef ABSL_SYNCHRONIZATION_BARRIER_H_
0020 #define ABSL_SYNCHRONIZATION_BARRIER_H_
0021
0022 #include "absl/base/thread_annotations.h"
0023 #include "absl/synchronization/mutex.h"
0024
0025 namespace absl {
0026 ABSL_NAMESPACE_BEGIN
0027
0028 // Barrier
0029 //
0030 // This class creates a barrier which blocks threads until a prespecified
0031 // threshold of threads (`num_threads`) utilizes the barrier. A thread utilizes
0032 // the `Barrier` by calling `Block()` on the barrier, which will block that
0033 // thread; no call to `Block()` will return until `num_threads` threads have
0034 // called it.
0035 //
0036 // Exactly one call to `Block()` will return `true`, which is then responsible
0037 // for destroying the barrier; because stack allocation will cause the barrier
0038 // to be deleted when it is out of scope, barriers should not be stack
0039 // allocated.
0040 //
0041 // Example:
0042 //
0043 //   // Main thread creates a `Barrier`:
0044 //   barrier = new Barrier(num_threads);
0045 //
0046 //   // Each participating thread could then call:
0047 //   if (barrier->Block()) delete barrier;  // Exactly one call to `Block()`
0048 //                                          // returns `true`; that call
0049 //                                          // deletes the barrier.
0050 class Barrier {
0051  public:
0052   // `num_threads` is the number of threads that will participate in the barrier
0053   explicit Barrier(int num_threads)
0054       : num_to_block_(num_threads), num_to_exit_(num_threads) {}
0055
0056   Barrier(const Barrier&) = delete;
0057   Barrier& operator=(const Barrier&) = delete;
0058
0059   // Barrier::Block()
0060   //
0061   // Blocks the current thread, and returns only when the `num_threads`
0062   // threshold of threads utilizing this barrier has been reached. `Block()`
0063   // returns `true` for precisely one caller, which may then destroy the
0064   // barrier.
0065   //
0066   // Memory ordering: For any threads X and Y, any action taken by X
0067   // before X calls `Block()` will be visible to Y after Y returns from
0068   // `Block()`.
0069   bool Block();
0070
0071  private:
0072   Mutex lock_;
0073   int num_to_block_ ABSL_GUARDED_BY(lock_);
0074   int num_to_exit_ ABSL_GUARDED_BY(lock_);
0075 };
0076
0077 ABSL_NAMESPACE_END
0078 }  // namespace absl
0079 #endif  // ABSL_SYNCHRONIZATION_BARRIER_H_