1 /* 2 * Copyright (C) 2011 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 #ifndef ART_RUNTIME_THREAD_LIST_H_ 18 #define ART_RUNTIME_THREAD_LIST_H_ 19 20 #include <bitset> 21 #include <list> 22 #include <vector> 23 24 #include "barrier.h" 25 #include "base/histogram.h" 26 #include "base/mutex.h" 27 #include "base/macros.h" 28 #include "base/value_object.h" 29 #include "jni.h" 30 #include "reflective_handle_scope.h" 31 #include "suspend_reason.h" 32 #include "thread_state.h" 33 34 namespace art HIDDEN { 35 namespace gc { 36 namespace collector { 37 class GarbageCollector; 38 } // namespace collector 39 class GcPauseListener; 40 } // namespace gc 41 class Closure; 42 class IsMarkedVisitor; 43 class RootVisitor; 44 class Thread; 45 class TimingLogger; 46 enum VisitRootFlags : uint8_t; 47 48 class ThreadList { 49 public: 50 static constexpr uint32_t kMaxThreadId = 0xFFFF; 51 static constexpr uint32_t kInvalidThreadId = 0; 52 static constexpr uint32_t kMainThreadId = 1; 53 static constexpr uint64_t kDefaultThreadSuspendTimeout = 54 kIsDebugBuild ? 2'000'000'000ull : 4'000'000'000ull; 55 // We fail more aggressively in debug builds to catch potential issues early. 56 // The number of times we may retry when we find ourselves in a suspend-unfriendly state. 57 static constexpr int kMaxSuspendRetries = kIsDebugBuild ? 500 : 5000; 58 static constexpr useconds_t kThreadSuspendSleepUs = 100; 59 60 explicit ThreadList(uint64_t thread_suspend_timeout_ns); 61 ~ThreadList(); 62 63 void ShutDown(); 64 65 void DumpForSigQuit(std::ostream& os) 66 REQUIRES(!Locks::thread_list_lock_, !Locks::mutator_lock_); 67 // For thread suspend timeout dumps. 68 EXPORT void Dump(std::ostream& os, bool dump_native_stack = true) 69 REQUIRES(!Locks::thread_list_lock_, !Locks::thread_suspend_count_lock_); 70 pid_t GetLockOwner(); // For SignalCatcher. 71 72 // Thread suspension support. 73 EXPORT void ResumeAll() 74 REQUIRES(!Locks::thread_list_lock_, !Locks::thread_suspend_count_lock_) 75 UNLOCK_FUNCTION(Locks::mutator_lock_); 76 EXPORT bool Resume(Thread* thread, SuspendReason reason = SuspendReason::kInternal) 77 REQUIRES(!Locks::thread_suspend_count_lock_) WARN_UNUSED; 78 79 // Suspends all other threads and gets exclusive access to the mutator lock. 80 // If long_suspend is true, then other threads who try to suspend will never timeout. 81 // long_suspend is currenly used for hprof since large heaps take a long time. 82 EXPORT void SuspendAll(const char* cause, bool long_suspend = false) 83 EXCLUSIVE_LOCK_FUNCTION(Locks::mutator_lock_) 84 REQUIRES(!Locks::thread_list_lock_, 85 !Locks::thread_suspend_count_lock_, 86 !Locks::mutator_lock_); 87 88 // Suspend a thread using a peer, typically used by the debugger. Returns the thread on success, 89 // else null. The peer is used to identify the thread to avoid races with the thread terminating. 90 EXPORT Thread* SuspendThreadByPeer(jobject peer, SuspendReason reason) 91 REQUIRES(!Locks::mutator_lock_, 92 !Locks::thread_list_lock_, 93 !Locks::thread_suspend_count_lock_); 94 95 // Suspend a thread using its thread id, typically used by lock/monitor inflation. Returns the 96 // thread on success else null. The thread id is used to identify the thread to avoid races with 97 // the thread terminating. Note that as thread ids are recycled this may not suspend the expected 98 // thread, that may be terminating. 'attempt_of_4' is zero if this is the only 99 // attempt, or 1..4 to try 4 times with fractional timeouts. 100 // TODO: Reconsider the use of thread_id, now that we have ThreadExitFlag. 101 Thread* SuspendThreadByThreadId(uint32_t thread_id, SuspendReason reason, int attempt_of_4 = 0) 102 REQUIRES(!Locks::mutator_lock_, 103 !Locks::thread_list_lock_, 104 !Locks::thread_suspend_count_lock_); 105 106 // Find an existing thread (or self) by its thread id (not tid). 107 EXPORT Thread* FindThreadByThreadId(uint32_t thread_id) REQUIRES(Locks::thread_list_lock_); 108 109 // Find an existing thread (or self) by its tid (not thread id). 110 Thread* FindThreadByTid(int tid) REQUIRES(Locks::thread_list_lock_); 111 112 // Does the thread list still contain the given thread, or one at the same address? 113 // Used by Monitor to provide (mostly accurate) debugging information. 114 bool Contains(Thread* thread) REQUIRES(Locks::thread_list_lock_); 115 116 // Run a checkpoint on all threads. Return the total number of threads for which the checkpoint 117 // function has been or will be called. 118 // 119 // Running threads are not suspended but run the checkpoint inside of the suspend check. The 120 // return value includes already suspended threads for b/24191051. Runs or requests the 121 // callback, if non-null, inside the thread_list_lock critical section after capturing the list 122 // of threads needing to run the checkpoint. 123 // 124 // Does not wait for completion of the checkpoint function in running threads. 125 // 126 // If the caller holds the mutator lock, or acquire_mutator_lock is true, then all instances of 127 // the checkpoint function are run with the mutator lock. Otherwise, since the checkpoint code 128 // may not acquire or release the mutator lock, the checkpoint will have no way to access Java 129 // data. 130 // 131 // If acquire_mutator_lock is true, it may be acquired repeatedly to avoid holding it for an 132 // extended period without checking for suspension requests. 133 // 134 // We capture a set of threads that simultaneously existed at one point in time, and ensure that 135 // they all run the checkpoint function. We make no guarantees about threads created after this 136 // set of threads was captured. If newly created threads require the effect of the checkpoint, 137 // the caller may update global state indicating that this is necessary, and newly created 138 // threads must act on that. It is possible that on return there will be threads which have not, 139 // and will not, run the checkpoint_function, and neither have/will any of their ancestors. 140 // 141 // TODO: Is it possible to simplify mutator_lock handling here? Should this wait for completion? 142 EXPORT size_t RunCheckpoint(Closure* checkpoint_function, 143 Closure* callback = nullptr, 144 bool allow_lock_checking = true, 145 bool acquire_mutator_lock = false) 146 REQUIRES(!Locks::thread_list_lock_, !Locks::thread_suspend_count_lock_); 147 148 // Convenience version of the above to disable lock checking inside Run function. Hopefully this 149 // and the third parameter above will eventually disappear. 150 size_t RunCheckpointUnchecked(Closure* checkpoint_function, Closure* callback = nullptr) 151 REQUIRES(!Locks::thread_list_lock_, !Locks::thread_suspend_count_lock_) { 152 return RunCheckpoint(checkpoint_function, callback, false); 153 } 154 155 // Run an empty checkpoint on threads. Wait until threads pass the next suspend point or are 156 // suspended. This is used to ensure that the threads finish or aren't in the middle of an 157 // in-flight mutator heap access (eg. a read barrier.) Runnable threads will respond by 158 // decrementing the empty checkpoint barrier count. This works even when the weak ref access is 159 // disabled. Only one concurrent use is currently supported. 160 void RunEmptyCheckpoint() 161 REQUIRES(!Locks::thread_list_lock_, !Locks::thread_suspend_count_lock_); 162 163 // Used to flip thread roots from from-space refs to to-space refs. Used only by the concurrent 164 // moving collectors during a GC, and hence cannot be called from multiple threads concurrently. 165 // 166 // Briefly suspends all threads to atomically install a checkpoint-like thread_flip_visitor 167 // function to be run on each thread. Run flip_callback while threads are suspended. 168 // Thread_flip_visitors are run by each thread before it becomes runnable, or by us. We do not 169 // return until all thread_flip_visitors have been run. 170 void FlipThreadRoots(Closure* thread_flip_visitor, 171 Closure* flip_callback, 172 gc::collector::GarbageCollector* collector, 173 gc::GcPauseListener* pause_listener) 174 REQUIRES(!Locks::mutator_lock_, 175 !Locks::thread_list_lock_, 176 !Locks::thread_suspend_count_lock_); 177 178 // Iterates over all the threads. 179 EXPORT void ForEach(void (*callback)(Thread*, void*), void* context) 180 REQUIRES(Locks::thread_list_lock_); 181 182 template<typename CallBack> ForEach(CallBack cb)183 void ForEach(CallBack cb) REQUIRES(Locks::thread_list_lock_) { 184 ForEach([](Thread* t, void* ctx) REQUIRES(Locks::thread_list_lock_) { 185 (*reinterpret_cast<CallBack*>(ctx))(t); 186 }, &cb); 187 } 188 189 // Add/remove current thread from list. 190 void Register(Thread* self) 191 REQUIRES(Locks::runtime_shutdown_lock_) 192 REQUIRES(!Locks::mutator_lock_, 193 !Locks::thread_list_lock_, 194 !Locks::thread_suspend_count_lock_); 195 void Unregister(Thread* self, bool should_run_callbacks) 196 REQUIRES(!Locks::mutator_lock_, 197 !Locks::thread_list_lock_, 198 !Locks::thread_suspend_count_lock_); 199 200 // Wait until there are no Unregister() requests in flight. Only makes sense when we know that 201 // no new calls can be made. e.g. because we're the last thread. 202 void WaitForUnregisterToComplete(Thread* self) REQUIRES(Locks::thread_list_lock_); 203 204 void VisitRoots(RootVisitor* visitor, VisitRootFlags flags) const 205 REQUIRES_SHARED(Locks::mutator_lock_); 206 207 void VisitRootsForSuspendedThreads(RootVisitor* visitor) 208 REQUIRES(!Locks::thread_list_lock_, !Locks::thread_suspend_count_lock_) 209 REQUIRES_SHARED(Locks::mutator_lock_); 210 211 void VisitReflectiveTargets(ReflectiveValueVisitor* visitor) const REQUIRES(Locks::mutator_lock_); 212 213 EXPORT void SweepInterpreterCaches(IsMarkedVisitor* visitor) const 214 REQUIRES(Locks::mutator_lock_, !Locks::thread_list_lock_); 215 216 // Return a copy of the thread list. GetList()217 std::list<Thread*> GetList() REQUIRES(Locks::thread_list_lock_) { 218 return list_; 219 } 220 Size()221 size_t Size() REQUIRES(Locks::thread_list_lock_) { return list_.size(); } 222 CheckOnly1Thread(Thread * self)223 void CheckOnly1Thread(Thread* self) REQUIRES(!Locks::thread_list_lock_) { 224 MutexLock mu(self, *Locks::thread_list_lock_); 225 CHECK_EQ(Size(), 1u); 226 } 227 228 void DumpNativeStacks(std::ostream& os) 229 REQUIRES(!Locks::thread_list_lock_); 230 EmptyCheckpointBarrier()231 Barrier* EmptyCheckpointBarrier() { 232 return empty_checkpoint_barrier_.get(); 233 } 234 235 void WaitForOtherNonDaemonThreadsToExit(bool check_no_birth = true) 236 REQUIRES(!Locks::thread_list_lock_, !Locks::thread_suspend_count_lock_, 237 !Locks::mutator_lock_); 238 239 // Wait for suspend barrier to reach zero. Return a string possibly containing diagnostic 240 // information on timeout, nothing on success. The argument t specifies a thread to monitor for 241 // the diagnostic information. If 0 is passed, we return an empty string on timeout. Normally 242 // the caller does not hold the mutator lock. See the comment at the call in 243 // RequestSynchronousCheckpoint for the only exception. 244 std::optional<std::string> WaitForSuspendBarrier(AtomicInteger* barrier, 245 pid_t t = 0, 246 int attempt_of_4 = 0) 247 REQUIRES(!Locks::thread_list_lock_, !Locks::thread_suspend_count_lock_); 248 249 private: 250 uint32_t AllocThreadId(Thread* self); 251 void ReleaseThreadId(Thread* self, uint32_t id) REQUIRES(!Locks::allocated_thread_ids_lock_); 252 253 void DumpUnattachedThreads(std::ostream& os, bool dump_native_stack) 254 REQUIRES(!Locks::thread_list_lock_); 255 256 void SuspendAllDaemonThreadsForShutdown() 257 REQUIRES(!Locks::thread_list_lock_, !Locks::thread_suspend_count_lock_); 258 259 void ResumeAllInternal(Thread* self) 260 REQUIRES(Locks::thread_list_lock_, Locks::thread_suspend_count_lock_) 261 UNLOCK_FUNCTION(Locks::mutator_lock_); 262 263 // Helper to actually suspend a single thread. This is called with thread_list_lock_ held and 264 // the caller guarantees that *thread is valid until that is released. We "release the mutator 265 // lock", by switching to self_state. 'attempt_of_4' is 0 if we only attempt once, and 1..4 if 266 // we are going to try 4 times with a quarter of the full timeout. 'func_name' is used only to 267 // identify ourselves for logging. 268 bool SuspendThread(Thread* self, 269 Thread* thread, 270 SuspendReason reason, 271 ThreadState self_state, 272 const char* func_name, 273 int attempt_of_4) RELEASE(Locks::thread_list_lock_) 274 RELEASE_SHARED(Locks::mutator_lock_); 275 276 void SuspendAllInternal(Thread* self, SuspendReason reason = SuspendReason::kInternal) 277 REQUIRES(!Locks::thread_list_lock_, 278 !Locks::thread_suspend_count_lock_, 279 !Locks::mutator_lock_); 280 281 void AssertOtherThreadsAreSuspended(Thread* self) 282 REQUIRES(!Locks::thread_list_lock_, !Locks::thread_suspend_count_lock_); 283 284 std::bitset<kMaxThreadId> allocated_ids_ GUARDED_BY(Locks::allocated_thread_ids_lock_); 285 286 // The actual list of all threads. 287 std::list<Thread*> list_ GUARDED_BY(Locks::thread_list_lock_); 288 289 // Ongoing suspend all requests, used to ensure threads added to list_ respect SuspendAll, and 290 // to ensure that only one SuspendAll ot FlipThreadRoots call is active at a time. The value is 291 // always either 0 or 1. Thread_suspend_count_lock must be held continuously while these two 292 // functions modify suspend counts of all other threads and modify suspend_all_count_ . 293 int suspend_all_count_ GUARDED_BY(Locks::thread_suspend_count_lock_); 294 295 // Number of threads unregistering, ~ThreadList blocks until this hits 0. 296 int unregistering_count_ GUARDED_BY(Locks::thread_list_lock_); 297 298 // Thread suspend time histogram. Only modified when all the threads are suspended, so guarding 299 // by mutator lock ensures no thread can read when another thread is modifying it. 300 Histogram<uint64_t> suspend_all_histogram_ GUARDED_BY(Locks::mutator_lock_); 301 302 // Whether or not the current thread suspension is long. 303 bool long_suspend_; 304 305 // Whether the shutdown function has been called. This is checked in the destructor. It is an 306 // error to destroy a ThreadList instance without first calling ShutDown(). 307 bool shut_down_; 308 309 // Thread suspension timeout in nanoseconds. 310 const uint64_t thread_suspend_timeout_ns_; 311 312 std::unique_ptr<Barrier> empty_checkpoint_barrier_; 313 314 friend class Thread; 315 316 friend class Mutex; 317 friend class BaseMutex; 318 319 DISALLOW_COPY_AND_ASSIGN(ThreadList); 320 }; 321 322 // Helper for suspending all threads and getting exclusive access to the mutator lock. 323 class ScopedSuspendAll : public ValueObject { 324 public: 325 EXPORT explicit ScopedSuspendAll(const char* cause, bool long_suspend = false) 326 EXCLUSIVE_LOCK_FUNCTION(Locks::mutator_lock_) 327 REQUIRES(!Locks::thread_list_lock_, 328 !Locks::thread_suspend_count_lock_, 329 !Locks::mutator_lock_); 330 // No REQUIRES(mutator_lock_) since the unlock function already asserts this. 331 EXPORT ~ScopedSuspendAll() 332 REQUIRES(!Locks::thread_list_lock_, !Locks::thread_suspend_count_lock_) 333 UNLOCK_FUNCTION(Locks::mutator_lock_); 334 }; 335 336 } // namespace art 337 338 #endif // ART_RUNTIME_THREAD_LIST_H_ 339