Bug ID: JDK-8273971 Clarify the specification of JNI DestroyJavaVM in relation to "unloading the VM"

Type: CSR
Component: hotspot
Sub-Component: runtime

Priority: P4
Status: Closed
Resolution: Approved
Fix Versions: 18

Submitted: 2021-09-20
Updated: 2021-10-08
Resolved: 2021-10-08

Summary
-------

Generalize the specification of `DestroyJavaVM` to refer to termination, and replace contradictory statements about the "unloading" of the VM.

Problem
-------

The specification for `DestroyJavaVM` contains the remnant of a historical note that unloading of the VM is not supported.  This appears as an isolated statement after the "Returns:" section of the function specification, and appears to directly contradict the function description which states "Unloads a Java VM".

Solution
--------

Generalize the specification of DestroyJavaVM to refer to termination, in a way compatible with the Hotspot implementation and other implementations.

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

Replace the function description:

> Unloads a Java VM and reclaims its resources.

with:

> Terminates the operation of the JVM, making a best-effort attempt to
> release resources.

Delete the final statement:

> Unloading of the VM is not supported.

Replace other references to "unloading" the VM with "terminating" the VM. These occur in the overview discussion of the "Invocation API" section.

> **Terminating** the VM
> 
> The `JNI_DestroyJavaVM()` function **terminates** a Java VM.
> 
> The VM waits until the current thread is the only non-daemon user
> thread before it actually **terminates**. User threads include both Java
> threads and attached native threads. This restriction exists because a
> Java thread or attached native thread may be holding system resources,
> such as locks, windows, and so on. The VM cannot automatically free
> these resources. By restricting the current thread to be the only
> running thread when the VM is **terminated**, the burden of releasing
> system resources held by arbitrary threads is on the programmer.

Moving to Approved.
08-10-2021
[~iklam] that reference is correct, we do unload native libraries when their associated classloader is GC'd.
08-10-2021
There is one more related mention of "unload" in the spec. Should we do anything about it? > In addition, native libraries can be unloaded when their corresponding class loaders are garbage collected.
08-10-2021
This CSR request has now been updated to reflect a change to the specification in preference to adding an Implementation Note.
08-10-2021
After much discussion with [~darcy] an alternative update to the specification would be to describe the function as: > Terminates the operation of the JVM, making a best-effort attempt to release resources. and remove the final statement that unloading of the VM is not supported.
06-10-2021
[~darcy] Setting aside the merits, or not, of a "specification" that allows a function to do A or B, the intent here is not to try and fix what is essentially an unimplementable specification for "destroying a VM" such that the Hotspot implementation can be seen to be valid. Such a change would require a much more extensive validation and consultation process (and frankly for no real benefit). Instead I simply want to clarify what the orphaned piece of contradictory text is actually alluding to in regards to the Hotspot implementation so that it doesn't confound readers of the specification. Also note that the existing single "Informational Note" in JNI_OnUnload_L is not an implementation note at all. The only existing reference to the Hotspot implementation is called out as an example in EnsureLocalCapacity.
21-09-2021
Moving to Provisional, not Approved. From an SE specification perspective, I think it would be fine if DestroyJavaVM said "Unloads a Java VM and reclaims its resources or does X" where "or does X" is what HotSpot does. The moral equivalent of an implNote, "Informational Note:" from elsewhere in the JNI spec, could then describe what HotSpot does in more detail.
21-09-2021