src/share/vm/runtime/thread.hpp

@@ -1884,14 +1884,32 @@
   // Includes JNI_VERSION_1_1
   static jboolean is_supported_jni_version_including_1_1(jint version);
   // Does not include JNI_VERSION_1_1
   static jboolean is_supported_jni_version(jint version);
 
+  // The "thread claim parity" provides a way for threads to be claimed
+  // by parallel worker tasks.
+  //
+  // Each thread contains a a "parity" field. A task will claim the
+  // thread only if its parity field is the same as the global parity,
+  // which is updated by calling change_thread_claim_parity().
+  //
+  // For this to work change_thread_claim_parity() needs to be called
+  // exactly once in sequential code before starting parallel tasks
+  // that should claim threads.
+  //
+  // If the client meats this spec, then "thread claim parity" will have
+  // the following properties:
+  //   a) to return a different value than was returned before the last
+  //      call to change_strong_roots_parity, and
+  //   c) to never return a distinguished value (zero) with which such
+  //      task-claiming variables may be initialized, to indicate "never
+  //      claimed".
   static int thread_claim_parity() { return _thread_claim_parity; }
   static void change_thread_claim_parity();
-
   static void assert_all_threads_claimed() PRODUCT_RETURN;
+
   // Apply "f->do_oop" to all root oops in all threads.
   // This version may only be called by sequential code.
   static void oops_do(OopClosure* f, CLDClosure* cld_f, CodeBlobClosure* cf);
   // This version may be called by sequential or parallel code.
   static void possibly_parallel_oops_do(bool is_par, OopClosure* f, CLDClosure* cld_f, CodeBlobClosure* cf);