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. Some names are unconventional.
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 spuriously 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 #include "base/macros.h"
34 
35 namespace art HIDDEN {
36 
37 class ConditionVariable;
38 class LOCKABLE Mutex;
39 
40 // TODO: Maybe give this a better name.
41 class Barrier {
42  public:
43   enum EXPORT LockHandling {
44     kAllowHoldingLocks,
45     kDisallowHoldingLocks,
46   };
47 
48   // If verify_count_on_shutdown is true, the destructor verifies that the count is zero in the
49   // destructor. This means that all expected threads went through the barrier.
50   EXPORT explicit Barrier(int count, bool verify_count_on_shutdown = true);
51   EXPORT virtual ~Barrier();
52 
53   // Pass through the barrier, decrement the count but do not block.
54   EXPORT void Pass(Thread* self) REQUIRES(!GetLock());
55   // Increment the barrier but do not block. The caller should ensure that it
56   // decrements/passes it eventually.
57   void IncrementNoWait(Thread* self) REQUIRES(!GetLock());
58 
59   // Decrement the count, then wait until the count is zero.
60   void Wait(Thread* self) REQUIRES(!GetLock());
61 
62   // The following three calls are only safe if we somehow know that no other thread both
63   // - has been woken up, and
64   // - has not left the Wait() or Increment() call.
65   // If these calls are made in that situation, the offending thread is likely to go back
66   // to sleep, resulting in a deadlock.
67 
68   // Increment the count by delta, wait on condition while count is non zero.  If LockHandling is
69   // kAllowHoldingLocks we will not check that all locks are released when waiting.
70   template <Barrier::LockHandling locks = kDisallowHoldingLocks>
71   EXPORT void Increment(Thread* self, int delta) REQUIRES(!GetLock());
72 
73   // Increment the count by delta, wait on condition while count is non zero, with a timeout.
74   // Returns true if time out occurred.
75   bool Increment(Thread* self, int delta, uint32_t timeout_ms) REQUIRES(!GetLock());
76 
77   // Set the count to a new value.  This should only be used if there is no possibility that
78   // another thread is still in Wait().  See above.
79   void Init(Thread* self, int count) REQUIRES(!GetLock());
80 
81   int GetCount(Thread* self) REQUIRES(!GetLock());
82 
83  private:
84   void SetCountLocked(Thread* self, int count) REQUIRES(GetLock());
85 
GetLock()86   Mutex* GetLock() {
87     return lock_.get();
88   }
89 
90   // Counter, when this reaches 0 all people blocked on the barrier are signalled.
91   int count_ GUARDED_BY(GetLock());
92 
93   std::unique_ptr<Mutex> lock_ ACQUIRED_AFTER(Locks::abort_lock_);
94   std::unique_ptr<ConditionVariable> condition_ GUARDED_BY(GetLock());
95   const bool verify_count_on_shutdown_;
96 };
97 
98 }  // namespace art
99 #endif  // ART_RUNTIME_BARRIER_H_
100