1 /*
2  * Copyright (C) 2012 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 // CAUTION: THIS IS NOT A FULLY GENERAL BARRIER API.
18 
19 // It may either be used as a "latch" or single-use barrier, or it may be reused under
20 // very limited conditions, e.g. if only Pass(), but not Wait() is called.  Unlike a standard
21 // latch API, it is possible to initialize the latch to a count of zero, repeatedly call
22 // Pass() or Wait(), and only then set the count using the Increment() method.  Threads at
23 // a Wait() are only awoken if the count reaches zero AFTER the decrement is applied.
24 // This works because, also unlike most latch APIs, there is no way to Wait() without
25 // decrementing the count, and thus nobody can spuriosly wake up on the initial zero.
26 
27 #ifndef ART_RUNTIME_BARRIER_H_
28 #define ART_RUNTIME_BARRIER_H_
29 
30 #include <memory>
31 
32 #include "base/locks.h"
33 
34 namespace art {
35 
36 class ConditionVariable;
37 class LOCKABLE Mutex;
38 
39 // TODO: Maybe give this a better name.
40 class Barrier {
41  public:
42   enum LockHandling {
43     kAllowHoldingLocks,
44     kDisallowHoldingLocks,
45   };
46 
47   // If verify_count_on_shutdown is true, the destructor verifies that the count is zero in the
48   // destructor. This means that all expected threads went through the barrier.
49   explicit Barrier(int count, bool verify_count_on_shutdown = true);
50   virtual ~Barrier();
51 
52   // Pass through the barrier, decrement the count but do not block.
53   void Pass(Thread* self) REQUIRES(!GetLock());
54 
55   // Wait on the barrier, decrement the count.
56   void Wait(Thread* self) REQUIRES(!GetLock());
57 
58   // The following three calls are only safe if we somehow know that no other thread both
59   // - has been woken up, and
60   // - has not left the Wait() or Increment() call.
61   // If these calls are made in that situation, the offending thread is likely to go back
62   // to sleep, resulting in a deadlock.
63 
64   // Increment the count by delta, wait on condition if count is non zero.  If LockHandling is
65   // kAllowHoldingLocks we will not check that all locks are released when waiting.
66   template <Barrier::LockHandling locks = kDisallowHoldingLocks>
67   void Increment(Thread* self, int delta) REQUIRES(!GetLock());
68 
69   // Increment the count by delta, wait on condition if count is non zero, with a timeout. Returns
70   // true if time out occurred.
71   bool Increment(Thread* self, int delta, uint32_t timeout_ms) REQUIRES(!GetLock());
72 
73   // Set the count to a new value.  This should only be used if there is no possibility that
74   // another thread is still in Wait().  See above.
75   void Init(Thread* self, int count) REQUIRES(!GetLock());
76 
77   int GetCount(Thread* self) REQUIRES(!GetLock());
78 
79  private:
80   void SetCountLocked(Thread* self, int count) REQUIRES(GetLock());
81 
GetLock()82   Mutex* GetLock() {
83     return lock_.get();
84   }
85 
86   // Counter, when this reaches 0 all people blocked on the barrier are signalled.
87   int count_ GUARDED_BY(GetLock());
88 
89   std::unique_ptr<Mutex> lock_ ACQUIRED_AFTER(Locks::abort_lock_);
90   std::unique_ptr<ConditionVariable> condition_ GUARDED_BY(GetLock());
91   const bool verify_count_on_shutdown_;
92 };
93 
94 }  // namespace art
95 #endif  // ART_RUNTIME_BARRIER_H_
96