JDK-8289190 : (jni spec) Description of 3rd parameter to AttachCurrentThread is confusing
  • Type: CSR
  • Component: hotspot
  • Sub-Component: runtime
  • Priority: P4
  • Status: Finalized
  • Resolution: Unresolved
  • Fix Versions: 20
  • Submitted: 2022-06-27
  • Updated: 2022-06-27
Related Reports
CSR :  
Description
Summary
-------

Two redundant and/or confusing sentences in relation to the arguments of `AttachCurrentThread` are removed.

Problem
-------

In Java 7, the spec was:

> In JDK 1.1, the second argument to `AttachCurrentThread` is always a
> pointer to `JNIEnv`. The third argument to `AttachCurrentThread` was
> reserved, and should be set to `NULL`.
> 
> In JDK 1.2, you pass `NULL` as the third argument for 1.1 behavior, or
> pass a pointer to the following structure to specify additional
> information:

In Java 8 it changed to just:

> The second argument to `AttachCurrentThread` is always a pointer to
> `JNIEnv`. The third argument to `AttachCurrentThread` was reserved, and
> should be set to `NULL`.

The sentence "The second argument .." is redundant as it just repeats the definition of the second argument.

The sentence "The third argument to ..." is not correct as it can be `NULL` or a pointer to a `JavaVMAttachArgs` structure when there is additional information to specify. 

Solution
--------

Delete both sentences. In doing so the following sentence also becomes redundant and can be removed:

> You pass a pointer to the following structure to specify additional information:

Specification
-------------

Before:

> PARAMETERS:
> 
> `vm`: the VM to which the current thread will be attached, must not be
> `NULL`.
> 
> `p_env`: pointer to the location where the JNI interface pointer of the
> current thread will be placed, must not be `NULL`.
> 
> `thr_args`: can be `NULL` or a pointer to a `JavaVMAttachArgs` structure to
> specify additional information:
> 
> The second argument to `AttachCurrentThread` is always a pointer to
> `JNIEnv`. The third argument to `AttachCurrentThread` was reserved, and
> should be set to `NULL`.
> 
> You pass a pointer to the following structure to specify additional
> information:
> 
>  `typedef struct JavaVMAttachArgs {` ...

After:

> PARAMETERS:
> 
> `vm`: the VM to which the current thread will be attached, must not be
> `NULL`.
> 
> `p_env`: pointer to the location where the JNI interface pointer of the
> current thread will be placed, must not be `NULL`.
> 
> `thr_args`: can be `NULL` or a pointer to a `JavaVMAttachArgs` structure to
> specify additional information:
> 
>  `typedef struct JavaVMAttachArgs {` ...

Comments
Thanks Alan! Now Finalized.
27-06-2022

[~alanb] please review. Thanks.
27-06-2022