On Tue, 4 Jun 2024 19:00:32 GMT, Chris Plummer <[email protected]> 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
