src/share/vm/runtime/thread.hpp

*** 1884,1897 ****
    // 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);
  
    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);
--- 1884,1915 ----
    // 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);