On Tue, 4 Jun 2024 19:00:32 GMT, Chris Plummer <cjplum...@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