src/hotspot/share/runtime/threadSMR.hpp

rev 47862 : imported patch 10.07.open.rebase_20171110.dcubed
rev 47867 : coleenp CR: Change ThreadsList::_threads from 'mtGC' -> 'mtThread', add header comment to threadSMR.hpp file, cleanup JavaThreadIteratorWithHandle ctr, make ErrorHandling more efficient.

*** 26,35 ****
--- 26,84 ----
  #define SHARE_VM_RUNTIME_THREADSMR_HPP
  
  #include "memory/allocation.hpp"
  #include "runtime/timer.hpp"
  
+ // Thread Safe Memory Reclaimation (Thread-SMR) support.
+ //
+ // ThreadsListHandles are used to safely perform operations on one or more
+ // threads without the risk of the thread or threads exiting during the
+ // operation. It is no longer necessary to hold the Threads_lock to safely
+ // perform an operation on a target thread.
+ //
+ // There are several different ways to refer to java.lang.Thread objects
+ // so we have a few ways to get a protected JavaThread *:
+ //
+ // JNI jobject example:
+ //   jobject jthread = ...;
+ //   :
+ //   ThreadsListHandle tlh;
+ //   JavaThread* jt = NULL;
+ //   bool is_alive = tlh.cv_internal_thread_to_JavaThread(jthread, &jt, NULL);
+ //   if (is_alive) {
+ //     :  // do stuff with 'jt'...
+ //   }
+ //
+ // JVM/TI jthread example:
+ //   jthread thread = ...;
+ //   :
+ //   JavaThread* jt = NULL;
+ //   ThreadsListHandle tlh;
+ //   jvmtiError err = JvmtiExport::cv_external_thread_to_JavaThread(tlh.list(), thread, &jt, NULL);
+ //   if (err != JVMTI_ERROR_NONE) {
+ //     return err;
+ //   }
+ //   :  // do stuff with 'jt'...
+ //
+ // JVM/TI oop example (this one should be very rare):
+ //   oop thread_obj = ...;
+ //   :
+ //   JavaThread *jt = NULL;
+ //   ThreadsListHandle tlh;
+ //   jvmtiError err = JvmtiExport::cv_oop_to_JavaThread(tlh.list(), thread_obj, &jt);
+ //   if (err != JVMTI_ERROR_NONE) {
+ //     return err;
+ //   }
+ //   :  // do stuff with 'jt'...
+ //
+ // A JavaThread * that is included in the ThreadsList that is held by
+ // a ThreadsListHandle is protected as long as the ThreadsListHandle
+ // remains in scope. The target JavaThread * may have logically exited,
+ // but that target JavaThread * will not be deleted until it is no
+ // longer protected by a ThreadsListHandle.
+ 
+ 
  // A fast list of JavaThreads.
  //
  class ThreadsList : public CHeapObj<mtThread> {
    friend class ScanHazardPtrGatherProtectedThreadsClosure;
    friend class Threads;
*** 181,191 ****
  class JavaThreadIteratorWithHandle : public StackObj {
    ThreadsListHandle _tlh;
    uint _index;
  
  public:
!   JavaThreadIteratorWithHandle() : _tlh(), _index(0) {}
  
    uint length() const {
      return _tlh.length();
    }
  
--- 230,240 ----
  class JavaThreadIteratorWithHandle : public StackObj {
    ThreadsListHandle _tlh;
    uint _index;
  
  public:
!   JavaThreadIteratorWithHandle() : _index(0) {}
  
    uint length() const {
      return _tlh.length();
    }