Class Runtime

public void addShutdownHook(Thread hook)

Register a new shutdown hook. This is invoked when the program exits normally (because all non-daemon threads ended, or because System.exit was invoked), or when the user terminates the virtual machine (such as by typing ^C, or logging off). There is a security check to add hooks, RuntimePermission("shutdownHooks").

The hook must be an initialized, but unstarted Thread. The threads are run concurrently, and started in an arbitrary order; and user threads or daemons may still be running. Once shutdown hooks have started, they must all complete, or else you must use halt, to actually finish the shutdown sequence. Attempts to modify hooks after shutdown has started result in IllegalStateExceptions.

It is imperative that you code shutdown hooks defensively, as you do not want to deadlock, and have no idea what other hooks will be running concurrently. It is also a good idea to finish quickly, as the virtual machine really wants to shut down!

There are no guarantees that such hooks will run, as there are ways to forcibly kill a process. But in such a drastic case, shutdown hooks would do little for you in the first place.

Parameters:

hook - an initialized, unstarted Thread

Throws:

IllegalArgumentException - if the hook is already registered or run

IllegalStateException - if the virtual machine is already in the shutdown sequence

SecurityException - if permission is denied

Since:

1.3

See Also:

removeShutdownHook(Thread), exit(int), halt(int)

public int availableProcessors()

Returns the number of available processors currently available to the virtual machine. This number may change over time; so a multi-processor program want to poll this to determine maximal resource usage.

Returns:

the number of processors available, at least 1

public Process exec(String cmdline)
            throws IOException

Create a new subprocess with the specified command line. Calls exec(cmdline, null, null). A security check is performed, checkExec.

Parameters:

cmdline - the command to call

Returns:

the Process object

Throws:

SecurityException - if permission is denied

IOException - if an I/O error occurs

NullPointerException - if cmdline is null

IndexOutOfBoundsException - if cmdline is ""

public Process exec(String cmdline,
                    String[] env)
            throws IOException

Create a new subprocess with the specified command line and environment. If the environment is null, the process inherits the environment of this process. Calls exec(cmdline, env, null). A security check is performed, checkExec.

Parameters:

cmdline - the command to call

env - the environment to use, in the format name=value

Returns:

the Process object

Throws:

SecurityException - if permission is denied

IOException - if an I/O error occurs

NullPointerException - if cmdline is null, or env has null entries

IndexOutOfBoundsException - if cmdline is ""

public Process exec(String cmdline,
                    String[] env,
                    File dir)
            throws IOException

Create a new subprocess with the specified command line, environment, and working directory. If the environment is null, the process inherits the environment of this process. If the directory is null, the process uses the current working directory. This splits cmdline into an array, using the default StringTokenizer, then calls exec(cmdArray, env, dir). A security check is performed, checkExec.

Parameters:

cmdline - the command to call

env - the environment to use, in the format name=value

dir - the working directory to use

Returns:

the Process object

Throws:

SecurityException - if permission is denied

IOException - if an I/O error occurs

NullPointerException - if cmdline is null, or env has null entries

IndexOutOfBoundsException - if cmdline is ""

Since:

1.3

public Process exec(String[] cmd)
            throws IOException

Create a new subprocess with the specified command line, already tokenized. Calls exec(cmd, null, null). A security check is performed, checkExec.

Parameters:

cmd - the command to call

Returns:

the Process object

Throws:

SecurityException - if permission is denied

IOException - if an I/O error occurs

NullPointerException - if cmd is null, or has null entries

IndexOutOfBoundsException - if cmd is length 0

public Process exec(String[] cmd,
                    String[] env)
            throws IOException

Create a new subprocess with the specified command line, already tokenized, and specified environment. If the environment is null, the process inherits the environment of this process. Calls exec(cmd, env, null). A security check is performed, checkExec.

Parameters:

cmd - the command to call

env - the environment to use, in the format name=value

Returns:

the Process object

Throws:

SecurityException - if permission is denied

IOException - if an I/O error occurs

NullPointerException - if cmd is null, or cmd or env has null entries

IndexOutOfBoundsException - if cmd is length 0

public Process exec(String[] cmd,
                    String[] env,
                    File dir)
            throws IOException

Create a new subprocess with the specified command line, already tokenized, and the specified environment and working directory. If the environment is null, the process inherits the environment of this process. If the directory is null, the process uses the current working directory. A security check is performed, checkExec.

Parameters:

cmd - the command to call

env - the environment to use, in the format name=value

dir - the working directory to use

Returns:

the Process object

Throws:

SecurityException - if permission is denied

IOException - if an I/O error occurs

NullPointerException - if cmd is null, or cmd or env has null entries

IndexOutOfBoundsException - if cmd is length 0

Since:

1.3

public void exit(int status)

Exit the Java runtime. This method will either throw a SecurityException or it will never return. The status code is returned to the system; often a non-zero status code indicates an abnormal exit. Of course, there is a security check, checkExit(status).

First, all shutdown hooks are run, in unspecified order, and concurrently. Next, if finalization on exit has been enabled, all pending finalizers are run. Finally, the system calls halt.

If this is run a second time after shutdown has already started, there are two actions. If shutdown hooks are still executing, it blocks indefinitely. Otherwise, if the status is nonzero it halts immediately; if it is zero, it blocks indefinitely. This is typically called by System.exit.

Parameters:

status - the status to exit with

Throws:

SecurityException - if permission is denied

See Also:

addShutdownHook(Thread), runFinalizersOnExit(boolean), runFinalization(), halt(int)

public long freeMemory()

Find out how much memory is still free for allocating Objects on the heap.

Returns:

the number of bytes of free memory for more Objects

public void gc()

Run the garbage collector. This method is more of a suggestion than anything. All this method guarantees is that the garbage collector will have "done its best" by the time it returns. Notice that garbage collection takes place even without calling this method.

public InputStream getLocalizedInputStream(InputStream in)

Deprecated. InputStreamReader is the preferred way to read local encodings

Return a localized version of this InputStream, meaning all characters are localized before they come out the other end.

Parameters:

in - the stream to localize

Returns:

the localized stream

public OutputStream getLocalizedOutputStream(OutputStream out)

Deprecated. OutputStreamWriter is the preferred way to write local encodings

Return a localized version of this OutputStream, meaning all characters are localized before they are sent to the other end.

Parameters:

out - the stream to localize

Returns:

the localized stream

public static Runtime getRuntime()

Get the current Runtime object for this JVM. This is necessary to access the many instance methods of this class.

Returns:

the current Runtime object

public void halt(int status)

Forcibly terminate the virtual machine. This call never returns. It is much more severe than exit, as it bypasses all shutdown hooks and initializers. Use caution in calling this! Of course, there is a security check, checkExit(status).

Parameters:

status - the status to exit with

Throws:

SecurityException - if permission is denied

Since:

1.3

See Also:

exit(int), addShutdownHook(Thread)

public void load(String filename)

Load a native library using the system-dependent filename. This is similar to loadLibrary, except the only name mangling done is inserting "_g" before the final ".so" if the VM was invoked by the name "java_g". There may be a security check, of checkLink.

The library is loaded using the class loader associated with the class associated with the invoking method.

Parameters:

filename - the file to load

Throws:

SecurityException - if permission is denied

public void loadLibrary(String libname)

Load a native library using a system-independent "short name" for the library. It will be transformed to a correct filename in a system-dependent manner (for example, in Windows, "mylib" will be turned into "mylib.dll"). This is done as follows: if the context that called load has a ClassLoader cl, then cl.findLibrary(libpath) is used to convert the name. If that result was null, or there was no class loader, this searches each directory of the system property java.library.path for a file named System.mapLibraryName(libname). There may be a security check, of checkLink.

Note: Besides java.library.path a VM may chose to search for native libraries in a path that is specified by the gnu.classpath.boot.library.path system property. However this is for internal usage or development of GNU Classpath only. A Java application must not load a non-system library by changing this property otherwise it will break compatibility.

The library is loaded using the class loader associated with the class associated with the invoking method.

Parameters:

libname - the library to load

Throws:

SecurityException - if permission is denied

See Also:

System.mapLibraryName(String), ClassLoader.findLibrary(String)

public long maxMemory()

Returns the maximum amount of memory the virtual machine can attempt to use. This may be Long.MAX_VALUE if there is no inherent limit (or if you really do have a 8 exabyte memory!).

Returns:

the maximum number of bytes the virtual machine will attempt to allocate

public boolean removeShutdownHook(Thread hook)

De-register a shutdown hook. As when you registered it, there is a security check to remove hooks, RuntimePermission("shutdownHooks").

Parameters:

hook - the hook to remove

Returns:

true if the hook was successfully removed, false if it was not registered in the first place

Throws:

IllegalStateException - if the virtual machine is already in the shutdown sequence

SecurityException - if permission is denied

Since:

1.3

See Also:

addShutdownHook(Thread), exit(int), halt(int)

public void runFinalization()

Run finalization on all Objects that are waiting to be finalized. Again, a suggestion, though a stronger one than gc(). This calls the finalize method of all objects waiting to be collected.

See Also:

finalize()

public static void runFinalizersOnExit(boolean finalizeOnExit)

Deprecated. never rely on finalizers to do a clean, thread-safe, mop-up from your code

Tell the VM to run the finalize() method on every single Object before it exits. Note that the JVM may still exit abnormally and not perform this, so you still don't have a guarantee. And besides that, this is inherently unsafe in multi-threaded code, as it may result in deadlock as multiple threads compete to manipulate objects. This value defaults to false. There is a security check, checkExit(0).

Parameters:

finalizeOnExit - whether to finalize all Objects on exit

Throws:

SecurityException - if permission is denied

Since:

1.1

See Also:

exit(int), gc()

public long totalMemory()

Find out how much memory total is available on the heap for allocating Objects.

Returns:

the total number of bytes of memory for Objects

public void traceInstructions(boolean on)

Tell the VM to trace every bytecode instruction that executes (print out a trace of it). No guarantees are made as to where it will be printed, and the VM is allowed to ignore this request.

Parameters:

on - whether to turn instruction tracing on

public void traceMethodCalls(boolean on)

Tell the VM to trace every method call that executes (print out a trace of it). No guarantees are made as to where it will be printed, and the VM is allowed to ignore this request.

Parameters:

on - whether to turn method tracing on