Add mutator collector coordination documentation
This affects a lot of ART and should thus be documented.
It is sufficiently low level that I believe it belongs in the source
tree. It should only be of interest to ART developers, in a broad sense
that includes anyone trying to understand failures involving ART.
Various comment improvements around thread suspension and checkpoints.
Test: Built AOSP.
Change-Id: I77338ff1d6f7c6aefb7be849449770438c15c982
diff --git a/runtime/thread_list.h b/runtime/thread_list.h
index 8fc219b..1dcdf62 100644
--- a/runtime/thread_list.h
+++ b/runtime/thread_list.h
@@ -108,11 +108,13 @@
// Used by Monitor to provide (mostly accurate) debugging information.
bool Contains(Thread* thread) REQUIRES(Locks::thread_list_lock_);
- // Run a checkpoint on threads, running threads are not suspended but run the checkpoint inside
- // of the suspend check. Returns how many checkpoints that are expected to run, including for
- // already suspended threads for b/24191051. Run the callback, if non-null, inside the
- // thread_list_lock critical section after determining the runnable/suspended states of the
- // threads.
+ // Run a checkpoint on all threads. Return the total number of threads for which the checkpoint
+ // function has been or will be called.
+ // Running threads are not suspended but run the checkpoint inside of the suspend check. The
+ // return value includes already suspended threads for b/24191051. Runs or requests the
+ // callback, if non-null, inside the thread_list_lock critical section after determining the
+ // runnable/suspended states of the threads. Does not wait for completion of the callbacks in
+ // running threads.
size_t RunCheckpoint(Closure* checkpoint_function, Closure* callback = nullptr)
REQUIRES(!Locks::thread_list_lock_, !Locks::thread_suspend_count_lock_);