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,10 +26,59 @@
 #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,11 +230,11 @@
 class JavaThreadIteratorWithHandle : public StackObj {
   ThreadsListHandle _tlh;
   uint _index;
 
 public:
-  JavaThreadIteratorWithHandle() : _tlh(), _index(0) {}
+  JavaThreadIteratorWithHandle() : _index(0) {}
 
   uint length() const {
     return _tlh.length();
   }