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

[Chris Plummer]

On Tue, 4 Jun 2024 23:52:36 GMT, Serguei Spitsyn <sspitsyn at openjdk.org> wrote:

>> 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.

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.

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

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