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 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 // Increment the barrier but do not block. The caller should ensure that it 55 // decrements/passes it eventually. 56 void IncrementNoWait(Thread* self) REQUIRES(!GetLock()); 57 58 // Decrement the count, then wait until the count is zero. 59 void Wait(Thread* self) REQUIRES(!GetLock()); 60 61 // The following three calls are only safe if we somehow know that no other thread both 62 // - has been woken up, and 63 // - has not left the Wait() or Increment() call. 64 // If these calls are made in that situation, the offending thread is likely to go back 65 // to sleep, resulting in a deadlock. 66 67 // Increment the count by delta, wait on condition while count is non zero. If LockHandling is 68 // kAllowHoldingLocks we will not check that all locks are released when waiting. 69 template <Barrier::LockHandling locks = kDisallowHoldingLocks> 70 void Increment(Thread* self, int delta) REQUIRES(!GetLock()); 71 72 // Increment the count by delta, wait on condition while count is non zero, with a timeout. 73 // Returns true if time out occurred. 74 bool Increment(Thread* self, int delta, uint32_t timeout_ms) REQUIRES(!GetLock()); 75 76 // Set the count to a new value. This should only be used if there is no possibility that 77 // another thread is still in Wait(). See above. 78 void Init(Thread* self, int count) REQUIRES(!GetLock()); 79 80 int GetCount(Thread* self) REQUIRES(!GetLock()); 81 82 private: 83 void SetCountLocked(Thread* self, int count) REQUIRES(GetLock()); 84 GetLock()85 Mutex* GetLock() { 86 return lock_.get(); 87 } 88 89 // Counter, when this reaches 0 all people blocked on the barrier are signalled. 90 int count_ GUARDED_BY(GetLock()); 91 92 std::unique_ptr<Mutex> lock_ ACQUIRED_AFTER(Locks::abort_lock_); 93 std::unique_ptr<ConditionVariable> condition_ GUARDED_BY(GetLock()); 94 const bool verify_count_on_shutdown_; 95 }; 96 97 } // namespace art 98 #endif // ART_RUNTIME_BARRIER_H_ 99