archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 23:04:50 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8302496: Runtime.exit incorrectly says it never throws an exception

Browse source 
Reviewed-by: alanb
This commit is contained in:
Stuart Marks 2023-05-02 23:19:30 +00:00
parent 8a70664e52
commit 05b9b5821d
2 changed files with 30 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

38
src/java.base/share/classes/java/lang/Runtime.java
View file

@ -140,19 +140,21 @@ public class Runtime {
private Runtime() {}
/**
* Initiates the <a href="#shutdown">shutdown sequence</a> of the Java Virtual Machine.
* This method blocks indefinitely; it never returns or throws an exception (that is, it
* does not complete either normally or abruptly). The argument serves as a status code;
* by convention, a nonzero status code indicates abnormal termination.
* Initiates the {@linkplain ##shutdown shutdown sequence} of the Java Virtual Machine.
* Unless the security manager denies exiting, this method initiates the shutdown sequence
* (if it is not already initiated) and then blocks indefinitely. This method neither returns
* nor throws an exception; that is, it does not complete either normally or abruptly.
*
* <p> Invocations of this method are serialized such that only one
* invocation will actually proceed with the shutdown sequence and
* terminate the VM with the given status code. All other invocations
* simply block indefinitely.
* <p> The argument serves as a status code. By convention, a nonzero status code
* indicates abnormal termination.
*
* <p> Because this method always blocks indefinitely, if it is invoked from
* a shutdown hook, it will prevent that shutdown hook from terminating.
* Consequently, this will prevent the shutdown sequence from finishing.
* <p> Successful invocations of this method are serialized such that only one invocation
* initiates the shutdown sequence and terminates the VM with the given status code.
* All other invocations will perform no action and block indefinitely.
*
* <p> Because a successful invocation of this method blocks indefinitely, if it is invoked
* from a shutdown hook, it will prevent that shutdown hook from terminating. Consequently,
* this will prevent the shutdown sequence from finishing.
*
* <p> The {@link System#exit(int) System.exit} method is the
* conventional and convenient means of invoking this method.
@ -190,7 +192,7 @@ public class Runtime {
* Registers a new virtual-machine shutdown hook.
*
* <p> A <i>shutdown hook</i> is simply an initialized but unstarted thread. Shutdown hooks
* are started at the beginning of the <a href="#shutdown">shutdown sequence</a>.
* are started at the beginning of the {@linkplain ##shutdown shutdown sequence}.
* Registration and de-registration of shutdown hooks is disallowed once the shutdown
* sequence has begun.
* <p>
@ -280,15 +282,17 @@ public class Runtime {
}
/**
* Immediately <a href="#termination">terminates</a> the Java Virtual Machine. Termination
* is unconditional and immediate. This method does not initiate the
* <a href="#shutdown">shutdown sequence</a>, nor does it wait for the shutdown sequence
* to finish if it is already in progress. This method never returns normally.
* Immediately {@linkplain ##termination terminates} the Java Virtual Machine.
* If the security manager denies exiting, throws {@link SecurityException}.
* Otherwise, termination of the Java Virtual Machine is unconditional and immediate.
* This method does not initiate the {@linkplain ##shutdown shutdown sequence}, nor does
* it wait for the shutdown sequence to finish if it is already in progress. An
* invocation of this method never returns normally.
*
* @apiNote
* This method should be used with extreme caution. Using it may circumvent or disrupt
* any cleanup actions intended to be performed by shutdown hooks, possibly leading to
* data corruption. See the <a href="#termination">termination</a> section above
* data corruption. See the {@linkplain ##termination termination} section above
* for other possible consequences of halting the Java Virtual Machine.
*
* @param status

18
src/java.base/share/classes/java/lang/System.java
View file

@ -1886,18 +1886,18 @@ public final class System {
}
/**
* Initiates the <a href="Runtime.html#shutdown">shutdown sequence</a> of the
* Java Virtual Machine. This method always blocks indefinitely. The argument
* serves as a status code; by convention, a nonzero status code indicates
* abnormal termination.
* Initiates the {@linkplain Runtime##shutdown shutdown sequence} of the Java Virtual Machine.
* Unless the security manager denies exiting, this method initiates the shutdown sequence
* (if it is not already initiated) and then blocks indefinitely. This method neither returns
* nor throws an exception; that is, it does not complete either normally or abruptly.
* <p>
* This method calls the {@code exit} method in class {@code Runtime}. This
* method never returns normally.
* The argument serves as a status code. By convention, a nonzero status code
* indicates abnormal termination.
* <p>
* The call {@code System.exit(n)} is effectively equivalent to the call:
* <blockquote><pre>
* Runtime.getRuntime().exit(n)
* </pre></blockquote>
* {@snippet :
* Runtime.getRuntime().exit(n)
* }
*
* @implNote
* The initiation of the shutdown sequence is logged by {@link Runtime#exit(int)}.