< prev index next >

src/java.base/share/classes/java/lang/Runtime.java

Print this page




  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.lang;
  27 
  28 import java.io.*;
  29 import java.math.BigInteger;
  30 import java.util.ArrayList;
  31 import java.util.regex.Matcher;
  32 import java.util.regex.Pattern;
  33 import java.util.stream.Collectors;
  34 import java.util.Collections;
  35 import java.util.List;
  36 import java.util.Optional;
  37 import java.util.StringTokenizer;


  38 import jdk.internal.reflect.CallerSensitive;
  39 import jdk.internal.reflect.Reflection;
  40 
  41 /**
  42  * Every Java application has a single instance of class
  43  * {@code Runtime} that allows the application to interface with
  44  * the environment in which the application is running. The current
  45  * runtime can be obtained from the {@code getRuntime} method.
  46  * <p>
  47  * An application cannot create its own instance of this class.
  48  *
  49  * @author  unascribed
  50  * @see     java.lang.Runtime#getRuntime()
  51  * @since   1.0
  52  */
  53 
  54 public class Runtime {
  55     private static final Runtime currentRuntime = new Runtime();
  56 
  57     private static Version version;


  60      * Returns the runtime object associated with the current Java application.
  61      * Most of the methods of class {@code Runtime} are instance
  62      * methods and must be invoked with respect to the current runtime object.
  63      *
  64      * @return  the {@code Runtime} object associated with the current
  65      *          Java application.
  66      */
  67     public static Runtime getRuntime() {
  68         return currentRuntime;
  69     }
  70 
  71     /** Don't let anyone else instantiate this class */
  72     private Runtime() {}
  73 
  74     /**
  75      * Terminates the currently running Java virtual machine by initiating its
  76      * shutdown sequence.  This method never returns normally.  The argument
  77      * serves as a status code; by convention, a nonzero status code indicates
  78      * abnormal termination.
  79      *
  80      * <p> The virtual machine's shutdown sequence consists of two phases.  In
  81      * the first phase all registered {@link #addShutdownHook shutdown hooks},
  82      * if any, are started in some unspecified order and allowed to run
  83      * concurrently until they finish.  In the second phase all uninvoked
  84      * finalizers are run if {@link #runFinalizersOnExit finalization-on-exit}
  85      * has been enabled.  Once this is done the virtual machine {@link #halt halts}.
  86      *
  87      * <p> If this method is invoked after the virtual machine has begun its
  88      * shutdown sequence then if shutdown hooks are being run this method will
  89      * block indefinitely.  If shutdown hooks have already been run and on-exit
  90      * finalization has been enabled then this method halts the virtual machine
  91      * with the given status code if the status is nonzero; otherwise, it
  92      * blocks indefinitely.
  93      *
  94      * <p> The {@link System#exit(int) System.exit} method is the
  95      * conventional and convenient means of invoking this method.
  96      *
  97      * @param  status
  98      *         Termination status.  By convention, a nonzero status code
  99      *         indicates abnormal termination.
 100      *
 101      * @throws SecurityException
 102      *         If a security manager is present and its
 103      *         {@link SecurityManager#checkExit checkExit} method does not permit
 104      *         exiting with the specified status
 105      *
 106      * @see java.lang.SecurityException
 107      * @see java.lang.SecurityManager#checkExit(int)
 108      * @see #addShutdownHook
 109      * @see #removeShutdownHook
 110      * @see #runFinalizersOnExit
 111      * @see #halt(int)
 112      */
 113     public void exit(int status) {
 114         SecurityManager security = System.getSecurityManager();
 115         if (security != null) {
 116             security.checkExit(status);
 117         }
 118         Shutdown.exit(status);
 119     }
 120 
 121     /**
 122      * Registers a new virtual-machine shutdown hook.
 123      *
 124      * <p> The Java virtual machine <i>shuts down</i> in response to two kinds
 125      * of events:
 126      *
 127      *   <ul>
 128      *
 129      *   <li> The program <i>exits</i> normally, when the last non-daemon
 130      *   thread exits or when the {@link #exit exit} (equivalently,
 131      *   {@link System#exit(int) System.exit}) method is invoked, or
 132      *
 133      *   <li> The virtual machine is <i>terminated</i> in response to a
 134      *   user interrupt, such as typing {@code ^C}, or a system-wide event,
 135      *   such as user logoff or system shutdown.
 136      *
 137      *   </ul>
 138      *
 139      * <p> A <i>shutdown hook</i> is simply an initialized but unstarted
 140      * thread.  When the virtual machine begins its shutdown sequence it will
 141      * start all registered shutdown hooks in some unspecified order and let
 142      * them run concurrently.  When all the hooks have finished it will then
 143      * run all uninvoked finalizers if finalization-on-exit has been enabled.
 144      * Finally, the virtual machine will halt.  Note that daemon threads will
 145      * continue to run during the shutdown sequence, as will non-daemon threads
 146      * if shutdown was initiated by invoking the {@link #exit exit} method.
 147      *
 148      * <p> Once the shutdown sequence has begun it can be stopped only by
 149      * invoking the {@link #halt halt} method, which forcibly
 150      * terminates the virtual machine.
 151      *
 152      * <p> Once the shutdown sequence has begun it is impossible to register a
 153      * new shutdown hook or de-register a previously-registered hook.
 154      * Attempting either of these operations will cause an
 155      * {@link IllegalStateException} to be thrown.
 156      *
 157      * <p> Shutdown hooks run at a delicate time in the life cycle of a virtual
 158      * machine and should therefore be coded defensively.  They should, in
 159      * particular, be written to be thread-safe and to avoid deadlocks insofar
 160      * as possible.  They should also not rely blindly upon services that may
 161      * have registered their own shutdown hooks and therefore may themselves in
 162      * the process of shutting down.  Attempts to use other thread-based
 163      * services such as the AWT event-dispatch thread, for example, may lead to
 164      * deadlocks.
 165      *
 166      * <p> Shutdown hooks should also finish their work quickly.  When a


 236      *          {@link RuntimePermission}("shutdownHooks")
 237      *
 238      * @see #addShutdownHook
 239      * @see #exit(int)
 240      * @since 1.3
 241      */
 242     public boolean removeShutdownHook(Thread hook) {
 243         SecurityManager sm = System.getSecurityManager();
 244         if (sm != null) {
 245             sm.checkPermission(new RuntimePermission("shutdownHooks"));
 246         }
 247         return ApplicationShutdownHooks.remove(hook);
 248     }
 249 
 250     /**
 251      * Forcibly terminates the currently running Java virtual machine.  This
 252      * method never returns normally.
 253      *
 254      * <p> This method should be used with extreme caution.  Unlike the
 255      * {@link #exit exit} method, this method does not cause shutdown
 256      * hooks to be started and does not run uninvoked finalizers if
 257      * finalization-on-exit has been enabled.  If the shutdown sequence has
 258      * already been initiated then this method does not wait for any running
 259      * shutdown hooks or finalizers to finish their work.
 260      *
 261      * @param  status
 262      *         Termination status. By convention, a nonzero status code
 263      *         indicates abnormal termination. If the {@link Runtime#exit exit}
 264      *         (equivalently, {@link System#exit(int) System.exit}) method
 265      *         has already been invoked then this status code
 266      *         will override the status code passed to that method.
 267      *
 268      * @throws SecurityException
 269      *         If a security manager is present and its
 270      *         {@link SecurityManager#checkExit checkExit} method
 271      *         does not permit an exit with the specified status
 272      *
 273      * @see #exit
 274      * @see #addShutdownHook
 275      * @see #removeShutdownHook
 276      * @since 1.3
 277      */
 278     public void halt(int status) {
 279         SecurityManager sm = System.getSecurityManager();
 280         if (sm != null) {
 281             sm.checkExit(status);
 282         }
 283         Shutdown.halt(status);
 284     }
 285 
 286     /**
 287      * Enable or disable finalization on exit; doing so specifies that the
 288      * finalizers of all objects that have finalizers that have not yet been
 289      * automatically invoked are to be run before the Java runtime exits.
 290      * By default, finalization on exit is disabled.
 291      *
 292      * <p>If there is a security manager,
 293      * its {@code checkExit} method is first called
 294      * with 0 as its argument to ensure the exit is allowed.
 295      * This could result in a SecurityException.
 296      *
 297      * @param value true to enable finalization on exit, false to disable
 298      * @deprecated  This method is inherently unsafe.  It may result in
 299      *      finalizers being called on live objects while other threads are
 300      *      concurrently manipulating those objects, resulting in erratic
 301      *      behavior or deadlock.
 302      *      This method is subject to removal in a future version of Java SE.
 303      *
 304      * @throws  SecurityException
 305      *        if a security manager exists and its {@code checkExit}
 306      *        method doesn't allow the exit.
 307      *
 308      * @see     java.lang.Runtime#exit(int)
 309      * @see     java.lang.Runtime#gc()
 310      * @see     java.lang.SecurityManager#checkExit(int)
 311      * @since   1.1
 312      */
 313     @Deprecated(since="1.2", forRemoval=true)
 314     public static void runFinalizersOnExit(boolean value) {
 315         SecurityManager security = System.getSecurityManager();
 316         if (security != null) {
 317             try {
 318                 security.checkExit(0);
 319             } catch (SecurityException e) {
 320                 throw new SecurityException("runFinalizersOnExit");
 321             }
 322         }
 323         Shutdown.setRunFinalizersOnExit(value);
 324     }
 325 
 326     /**
 327      * Executes the specified string command in a separate process.
 328      *
 329      * <p>This is a convenience method.  An invocation of the form
 330      * {@code exec(command)}
 331      * behaves in exactly the same way as the invocation
 332      * {@link #exec(String, String[], File) exec}{@code (command, null, null)}.
 333      *
 334      * @param   command   a specified system command.
 335      *
 336      * @return  A new {@link Process} object for managing the subprocess
 337      *
 338      * @throws  SecurityException
 339      *          If a security manager exists and its
 340      *          {@link SecurityManager#checkExec checkExec}
 341      *          method doesn't allow creation of the subprocess
 342      *
 343      * @throws  IOException
 344      *          If an I/O error occurs
 345      *
 346      * @throws  NullPointerException


 685     public native long maxMemory();
 686 
 687     /**
 688      * Runs the garbage collector.
 689      * Calling this method suggests that the Java virtual machine expend
 690      * effort toward recycling unused objects in order to make the memory
 691      * they currently occupy available for quick reuse. When control
 692      * returns from the method call, the virtual machine has made
 693      * its best effort to recycle all discarded objects.
 694      * <p>
 695      * The name {@code gc} stands for "garbage
 696      * collector". The virtual machine performs this recycling
 697      * process automatically as needed, in a separate thread, even if the
 698      * {@code gc} method is not invoked explicitly.
 699      * <p>
 700      * The method {@link System#gc()} is the conventional and convenient
 701      * means of invoking this method.
 702      */
 703     public native void gc();
 704 
 705     /* Wormhole for calling java.lang.ref.Finalizer.runFinalization */
 706     private static native void runFinalization0();
 707 
 708     /**
 709      * Runs the finalization methods of any objects pending finalization.
 710      * Calling this method suggests that the Java virtual machine expend
 711      * effort toward running the {@code finalize} methods of objects
 712      * that have been found to be discarded but whose {@code finalize}
 713      * methods have not yet been run. When control returns from the
 714      * method call, the virtual machine has made a best effort to
 715      * complete all outstanding finalizations.
 716      * <p>
 717      * The virtual machine performs the finalization process
 718      * automatically as needed, in a separate thread, if the
 719      * {@code runFinalization} method is not invoked explicitly.
 720      * <p>
 721      * The method {@link System#runFinalization()} is the conventional
 722      * and convenient means of invoking this method.
 723      *
 724      * @see     java.lang.Object#finalize()
 725      */
 726     public void runFinalization() {
 727         runFinalization0();
 728     }
 729 
 730     /**
 731      * Not implemented, does nothing.
 732      *
 733      * @deprecated
 734      * This method was intended to control instruction tracing.
 735      * It has been superseded by JVM-specific tracing mechanisms.
 736      * This method is subject to removal in a future version of Java SE.
 737      *
 738      * @param on ignored
 739      */
 740     @Deprecated(since="9", forRemoval=true)
 741     public void traceInstructions(boolean on) { }
 742 
 743     /**
 744      * Not implemented, does nothing.
 745      *
 746      * @deprecated
 747      * This method was intended to control method call tracing.




  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.lang;
  27 
  28 import java.io.*;
  29 import java.math.BigInteger;
  30 import java.util.ArrayList;
  31 import java.util.regex.Matcher;
  32 import java.util.regex.Pattern;
  33 import java.util.stream.Collectors;
  34 import java.util.Collections;
  35 import java.util.List;
  36 import java.util.Optional;
  37 import java.util.StringTokenizer;
  38 
  39 import jdk.internal.misc.SharedSecrets;
  40 import jdk.internal.reflect.CallerSensitive;
  41 import jdk.internal.reflect.Reflection;
  42 
  43 /**
  44  * Every Java application has a single instance of class
  45  * {@code Runtime} that allows the application to interface with
  46  * the environment in which the application is running. The current
  47  * runtime can be obtained from the {@code getRuntime} method.
  48  * <p>
  49  * An application cannot create its own instance of this class.
  50  *
  51  * @author  unascribed
  52  * @see     java.lang.Runtime#getRuntime()
  53  * @since   1.0
  54  */
  55 
  56 public class Runtime {
  57     private static final Runtime currentRuntime = new Runtime();
  58 
  59     private static Version version;


  62      * Returns the runtime object associated with the current Java application.
  63      * Most of the methods of class {@code Runtime} are instance
  64      * methods and must be invoked with respect to the current runtime object.
  65      *
  66      * @return  the {@code Runtime} object associated with the current
  67      *          Java application.
  68      */
  69     public static Runtime getRuntime() {
  70         return currentRuntime;
  71     }
  72 
  73     /** Don't let anyone else instantiate this class */
  74     private Runtime() {}
  75 
  76     /**
  77      * Terminates the currently running Java virtual machine by initiating its
  78      * shutdown sequence.  This method never returns normally.  The argument
  79      * serves as a status code; by convention, a nonzero status code indicates
  80      * abnormal termination.
  81      *
  82      * <p> All registered {@link #addShutdownHook shutdown hooks}, if any,
  83      * are started in some unspecified order and allowed to run concurrently
  84      * until they finish.  Once this is done the virtual machine
  85      * {@link #halt halts}.
  86      *
  87      * <p> If this method is invoked after the virtual machine has started
  88      * shutdown hooks then if shutdown hooks have already been run and
  89      * the status is nonzero then this method halts the virtual machine
  90      * with the given status code; otherwise, this method blocks indefinitely
  91      * (i.e. if shutdown hooks are being run or if shutdown hooks have already
  92      * been run and the status is zero).


  93      *
  94      * <p> The {@link System#exit(int) System.exit} method is the
  95      * conventional and convenient means of invoking this method.
  96      *
  97      * @param  status
  98      *         Termination status.  By convention, a nonzero status code
  99      *         indicates abnormal termination.
 100      *
 101      * @throws SecurityException
 102      *         If a security manager is present and its
 103      *         {@link SecurityManager#checkExit checkExit} method does not permit
 104      *         exiting with the specified status
 105      *
 106      * @see java.lang.SecurityException
 107      * @see java.lang.SecurityManager#checkExit(int)
 108      * @see #addShutdownHook
 109      * @see #removeShutdownHook

 110      * @see #halt(int)
 111      */
 112     public void exit(int status) {
 113         SecurityManager security = System.getSecurityManager();
 114         if (security != null) {
 115             security.checkExit(status);
 116         }
 117         Shutdown.exit(status);
 118     }
 119 
 120     /**
 121      * Registers a new virtual-machine shutdown hook.
 122      *
 123      * <p> The Java virtual machine <i>shuts down</i> in response to two kinds
 124      * of events:
 125      *
 126      *   <ul>
 127      *
 128      *   <li> The program <i>exits</i> normally, when the last non-daemon
 129      *   thread exits or when the {@link #exit exit} (equivalently,
 130      *   {@link System#exit(int) System.exit}) method is invoked, or
 131      *
 132      *   <li> The virtual machine is <i>terminated</i> in response to a
 133      *   user interrupt, such as typing {@code ^C}, or a system-wide event,
 134      *   such as user logoff or system shutdown.
 135      *
 136      *   </ul>
 137      *
 138      * <p> A <i>shutdown hook</i> is simply an initialized but unstarted
 139      * thread.  When the virtual machine begins its shutdown sequence it will
 140      * start all registered shutdown hooks in some unspecified order and let
 141      * them run concurrently.  When all the hooks have finished it will then
 142      * halt. Note that daemon threads will continue to run during the shutdown
 143      * sequence, as will non-daemon threads if shutdown was initiated by
 144      * invoking the {@link #exit exit} method.

 145      *
 146      * <p> Once the shutdown sequence has begun it can be stopped only by
 147      * invoking the {@link #halt halt} method, which forcibly
 148      * terminates the virtual machine.
 149      *
 150      * <p> Once the shutdown sequence has begun it is impossible to register a
 151      * new shutdown hook or de-register a previously-registered hook.
 152      * Attempting either of these operations will cause an
 153      * {@link IllegalStateException} to be thrown.
 154      *
 155      * <p> Shutdown hooks run at a delicate time in the life cycle of a virtual
 156      * machine and should therefore be coded defensively.  They should, in
 157      * particular, be written to be thread-safe and to avoid deadlocks insofar
 158      * as possible.  They should also not rely blindly upon services that may
 159      * have registered their own shutdown hooks and therefore may themselves in
 160      * the process of shutting down.  Attempts to use other thread-based
 161      * services such as the AWT event-dispatch thread, for example, may lead to
 162      * deadlocks.
 163      *
 164      * <p> Shutdown hooks should also finish their work quickly.  When a


 234      *          {@link RuntimePermission}("shutdownHooks")
 235      *
 236      * @see #addShutdownHook
 237      * @see #exit(int)
 238      * @since 1.3
 239      */
 240     public boolean removeShutdownHook(Thread hook) {
 241         SecurityManager sm = System.getSecurityManager();
 242         if (sm != null) {
 243             sm.checkPermission(new RuntimePermission("shutdownHooks"));
 244         }
 245         return ApplicationShutdownHooks.remove(hook);
 246     }
 247 
 248     /**
 249      * Forcibly terminates the currently running Java virtual machine.  This
 250      * method never returns normally.
 251      *
 252      * <p> This method should be used with extreme caution.  Unlike the
 253      * {@link #exit exit} method, this method does not cause shutdown
 254      * hooks to be started.  If the shutdown sequence has already been
 255      * initiated then this method does not wait for any running
 256      * shutdown hooks to finish their work.

 257      *
 258      * @param  status
 259      *         Termination status. By convention, a nonzero status code
 260      *         indicates abnormal termination. If the {@link Runtime#exit exit}
 261      *         (equivalently, {@link System#exit(int) System.exit}) method
 262      *         has already been invoked then this status code
 263      *         will override the status code passed to that method.
 264      *
 265      * @throws SecurityException
 266      *         If a security manager is present and its
 267      *         {@link SecurityManager#checkExit checkExit} method
 268      *         does not permit an exit with the specified status
 269      *
 270      * @see #exit
 271      * @see #addShutdownHook
 272      * @see #removeShutdownHook
 273      * @since 1.3
 274      */
 275     public void halt(int status) {
 276         SecurityManager sm = System.getSecurityManager();
 277         if (sm != null) {
 278             sm.checkExit(status);
 279         }
 280         Shutdown.halt(status);
 281     }
 282 
 283     /**








































 284      * Executes the specified string command in a separate process.
 285      *
 286      * <p>This is a convenience method.  An invocation of the form
 287      * {@code exec(command)}
 288      * behaves in exactly the same way as the invocation
 289      * {@link #exec(String, String[], File) exec}{@code (command, null, null)}.
 290      *
 291      * @param   command   a specified system command.
 292      *
 293      * @return  A new {@link Process} object for managing the subprocess
 294      *
 295      * @throws  SecurityException
 296      *          If a security manager exists and its
 297      *          {@link SecurityManager#checkExec checkExec}
 298      *          method doesn't allow creation of the subprocess
 299      *
 300      * @throws  IOException
 301      *          If an I/O error occurs
 302      *
 303      * @throws  NullPointerException


 642     public native long maxMemory();
 643 
 644     /**
 645      * Runs the garbage collector.
 646      * Calling this method suggests that the Java virtual machine expend
 647      * effort toward recycling unused objects in order to make the memory
 648      * they currently occupy available for quick reuse. When control
 649      * returns from the method call, the virtual machine has made
 650      * its best effort to recycle all discarded objects.
 651      * <p>
 652      * The name {@code gc} stands for "garbage
 653      * collector". The virtual machine performs this recycling
 654      * process automatically as needed, in a separate thread, even if the
 655      * {@code gc} method is not invoked explicitly.
 656      * <p>
 657      * The method {@link System#gc()} is the conventional and convenient
 658      * means of invoking this method.
 659      */
 660     public native void gc();
 661 



 662     /**
 663      * Runs the finalization methods of any objects pending finalization.
 664      * Calling this method suggests that the Java virtual machine expend
 665      * effort toward running the {@code finalize} methods of objects
 666      * that have been found to be discarded but whose {@code finalize}
 667      * methods have not yet been run. When control returns from the
 668      * method call, the virtual machine has made a best effort to
 669      * complete all outstanding finalizations.
 670      * <p>
 671      * The virtual machine performs the finalization process
 672      * automatically as needed, in a separate thread, if the
 673      * {@code runFinalization} method is not invoked explicitly.
 674      * <p>
 675      * The method {@link System#runFinalization()} is the conventional
 676      * and convenient means of invoking this method.
 677      *
 678      * @see     java.lang.Object#finalize()
 679      */
 680     public void runFinalization() {
 681         SharedSecrets.getJavaLangRefAccess().runFinalization();
 682     }
 683 
 684     /**
 685      * Not implemented, does nothing.
 686      *
 687      * @deprecated
 688      * This method was intended to control instruction tracing.
 689      * It has been superseded by JVM-specific tracing mechanisms.
 690      * This method is subject to removal in a future version of Java SE.
 691      *
 692      * @param on ignored
 693      */
 694     @Deprecated(since="9", forRemoval=true)
 695     public void traceInstructions(boolean on) { }
 696 
 697     /**
 698      * Not implemented, does nothing.
 699      *
 700      * @deprecated
 701      * This method was intended to control method call tracing.


< prev index next >