RFR: 8326716: JVMTI spec: clarify what nullptr means for C/C++ developers [v5]

[Serguei Spitsyn]

On Tue, 4 Jun 2024 19:00:32 GMT, Chris Plummer <cjplummer at openjdk.org> wrote:

>> I think this is the right place but it is only for return values. There are a few functions where a parameter value can be a null pointer, e.g. in GetThreadState, SuspendThread, GetOwnedMonitorInfo the thread parameter can be a null pointer to mean the current thread.  I don't think the introduction section has anywhere right now to reference for parameters that can be NULL/nullptr.
>
> Yes, my point was that this section is only for return values. The section is titled "Function Return Values". Maybe we should add another short section just before this one to describe what is meant by "null pointer".

Okay, thanks. What about the following: :

diff --git a/src/hotspot/share/prims/jvmti.xml b/src/hotspot/share/prims/jvmti.xml
index a6ebd0d42c5..a81014c70bb 100644
--- a/src/hotspot/share/prims/jvmti.xml
+++ b/src/hotspot/share/prims/jvmti.xml
@@ -995,7 +995,10 @@ jvmtiEnv *jvmti;
     across threads and are created dynamically.
   </intro>
 
-  <intro id="functionReturn" label="Function Return Values">
+  <intro id="functionReturn" label="Function Parameters and Return Values">
+    There are a few <jvmti/> functions where a parameter value can be a null pointer
+    (C <code>NULL</code> or C++ <code>nullptr</code>), e.g. the thread parameter
+    can be a null pointer to mean the current thread.
     <jvmti/> functions always return an
     <internallink id="ErrorSection">error code</internallink> via the
     <datalink id="jvmtiError"/> function return value.
@@ -1004,7 +1007,7 @@ jvmtiEnv *jvmti;
     In some cases, <jvmti/> functions allocate memory that your program must
     explicitly deallocate. This is indicated in the individual <jvmti/>
     function descriptions.  Empty lists, arrays, sequences, etc are
-    returned as a null pointer (C <code>NULL</code> or C++ <code>nullptr</code>).
+    returned as a null pointer.
     <p/>
     In the event that the <jvmti/> function encounters
     an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values


I can try to add a couple of more examples where a null pointer can be passed as a parameter value if it is desirable.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/19257#discussion_r1626756885