Summary

Clarify that if JNI_COMMIT mode is used for a copy, then a final call with mode 0 or JNI_ABORT must be made to free the copy.

Problem

The Release<T>ArrayElements API uses a "release mode" to determine how to update the target array and how to free it if it were a copy. If only mode 0 is used then there are no issues. However if mode JNI_COMMIT is used with an API that introduces a copy of the array, then that copy will "leak" if a second call to the appropriate "release" function is not made with a mode that causes the copy to be freed.

Solution

Clarify that if JNI_COMMIT mode is used for a copy, then a final call with mode 0 or JNI_ABORT must be made to free the copy.

Specification

> --- a/closed/src/java.se/share/specs/jni/functions.md
> +++ b/closed/src/java.se/share/specs/jni/functions.md @@ -3101,10 +3101,12 @@ table:
> 
>    : Primitive Array Release Modes
> 
> -In most cases, programmers pass "0" to the `mode` argument to ensure consistent
> +In most cases, programmers pass "0" as the `mode` argument to ensure consistent  
> behavior for both pinned and copied arrays. The other options give the
> programmer more control over memory management and should be used with extreme
> -care.
> +care. If `JNI_COMMIT` is passed as the `mode` argument when `elems is a copy of
> +the elements in `array`, then a final call to *Release\<PrimitiveType\>ArrayElements*
> +passing a `mode` argument of "0" or `JNI_ABORT`, should be made to free the `elems` buffer.