Summary

Clarify Agent_OnUnload specification to state that a VM need not call it if Agent_OnLoad or Agent_OnAttach fails.

Problem

The JVMTI specification of Agent_OnUnload says this function will be called when the agent library will be unloaded by a platform specific mechanism. It also says Agent_OnUnload() will be called both at VM termination and for other reasons.

The specification doesn't say anything for the case where Agent_OnAttach() fails. Currently HotSpot does not call Agent_OnUnload() when Agent_OnLoad() or Agent_OnAttach() fails (it means they return a value other than zero). So current Hotspot behaviour, while reasonable, seems outside of the specification.

Solution

Clarify the specification so that Agent_OnUnload() need not be called if Agent_OnLoad() or Agent_OnAttach() fails.

Specification

diff --git a/src/hotspot/share/prims/jvmti.xml b/src/hotspot/share/prims/jvmti.xml
index 44553b8065f..ad55f34a543 100644
--- a/src/hotspot/share/prims/jvmti.xml
+++ b/src/hotspot/share/prims/jvmti.xml
@@ -686,9 +686,11 @@ Agent_OnUnload_L(JavaVM *vm)</example>
     The library will be unloaded (unless it is statically linked into the
     executable) and this function will be called if some platform specific
     mechanism causes the unload (an unload mechanism is not specified in this document)
-    or the library is (in effect) unloaded by the termination of the VM whether through
-    normal termination or VM failure, including start-up failure.
-    Uncontrolled shutdown is, of course, an exception to this rule.
+    or the library is (in effect) unloaded by the termination of the VM.
+    VM termination includes normal termination and VM failure, including start-up failure,
+    but not, of course, uncontrolled shutdown. An implementation may also
+    choose to not call this function if the <code>Agent_OnAttach</code>/
+    <code>Agent_OnAttach_L</code> function reported an error (returned a non-zero value).
     Note the distinction between this function and the
     <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event
     to be sent, the VM must have run at least to the point of initialization and a valid