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