8328679: Improve comment for UNSAFE_ENTRY_SCOPED in unsafe.cpp

Reviewed-by: jvernee, dholmes

src/hotspot/share/prims/unsafe.cpp

@@ -76,25 +76,26 @@
 #define UNSAFE_LEAF(result_type, header) \
   JVM_LEAF(static result_type, header)
 
-// Note that scoped accesses (cf. scopedMemoryAccess.cpp) can install
+// All memory access methods (e.g. getInt, copyMemory) must use this macro.
-// an async handshake on the entry to an Unsafe method. When that happens,
+// We call these methods "scoped" methods, as access to these methods is
-// it is expected that we are not allowed to touch the underlying memory
+// typically governed by a "scope" (a MemorySessionImpl object), and no
-// that might have gotten unmapped. Therefore, we check at the entry
+// access is allowed when the scope is no longer alive.
-// to unsafe functions, if we have such async exception conditions,
-// and return immediately if that is the case.
 //
-// We can't have safepoints in this code.
+// Closing a scope object (cf. scopedMemoryAccess.cpp) can install
-// It would be problematic if an async exception handshake were installed later on
+// an async exception during a safepoint. When that happens,
-// during another safepoint in the function, but before the memory access happens,
+// scoped methods are not allowed to touch the underlying memory (as that
-// as the memory will be freed after the handshake is installed. We must notice
+// memory might have been released). Therefore, when entering a scoped method
-// the installed handshake and return early before doing the memory access to prevent
+// we check if an async exception has been installed, and return immediately
-// accesses to freed memory.
+// if that is the case.
 //
-// Note also that we MUST do a scoped memory access in the VM (or Java) thread
+// As a rule, we disallow safepoints in the middle of a scoped method.
-// state. Since we rely on a handshake to check for threads that are accessing
+// If an async exception handshake were installed in such a safepoint,
-// scoped memory, and we need the handshaking thread to wait until we get to a
+// memory access might still occur before the handshake is honored by
-// safepoint, in order to make sure we are not in the middle of accessing memory
+// the accessing thread.
-// that is about to be freed. (i.e. there can be no UNSAFE_LEAF_SCOPED)
+//
+// Corollary: as threads in native state are considered to be at a safepoint,
+// scoped methods must NOT be executed while in the native thread state.
+// Because of this, there can be no UNSAFE_LEAF_SCOPED.
 #define UNSAFE_ENTRY_SCOPED(result_type, header) \
   JVM_ENTRY(static result_type, header) \
   if (thread->has_async_exception_condition()) {return (result_type)0;}