On Wed, 5 Jun 2024 17:00:34 GMT, Chris Plummer <cjplum...@openjdk.org> wrote:
>> 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. > > I'm still not sure this works. It seems kind of muddled. Rather than trying > to retrofit in the clarifying text, why not start from scratch. That should > result in better organization and clearer descriptions. For example, I think > first you should clarify what is meant by a "null pointer". Maybe even make > that a separate section. I can take a stab at this later today if you want. How about undoing the changes in this subsection and then just add the following as a preceding subsection: **Null Pointers** Parts of this specification refer to a "null pointer" as a possible function parameter or return value. A "null pointer" is C `NULL` or C++ `nullptr`. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/19257#discussion_r1628532037
