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

[Chris Plummer]

On Wed, 5 Jun 2024 17:00:34 GMT, Chris Plummer <cjplummer at 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