java.lang

Class Runtime


public class Runtime
extends Object

Runtime represents the Virtual Machine.

Method Summary

void
addShutdownHook(Thread hook)
Register a new shutdown hook.
int
availableProcessors()
Returns the number of available processors currently available to the virtual machine.
Process
exec(String cmdline)
Create a new subprocess with the specified command line.
Process
exec(String cmdline, String[] env)
Create a new subprocess with the specified command line and environment.
Process
exec(String cmdline, String[] env, File dir)
Create a new subprocess with the specified command line, environment, and working directory.
Process
exec(String[] cmd)
Create a new subprocess with the specified command line, already tokenized.
Process
exec(String[] cmd, String[] env)
Create a new subprocess with the specified command line, already tokenized, and specified environment.
Process
exec(String[] cmd, String[] env, File dir)
Create a new subprocess with the specified command line, already tokenized, and the specified environment and working directory.
void
exit(int status)
Exit the Java runtime.
long
freeMemory()
Find out how much memory is still free for allocating Objects on the heap.
void
gc()
Run the garbage collector.
InputStream
getLocalizedInputStream(InputStream in)
Deprecated. InputStreamReader is the preferred way to read local encodings
OutputStream
getLocalizedOutputStream(OutputStream out)
Deprecated. OutputStreamWriter is the preferred way to write local encodings
static Runtime
getRuntime()
Get the current Runtime object for this JVM.
void
halt(int status)
Forcibly terminate the virtual machine.
void
load(String filename)
Load a native library using the system-dependent filename.
void
loadLibrary(String libname)
Load a native library using a system-independent "short name" for the library.
long
maxMemory()
Returns the maximum amount of memory the virtual machine can attempt to use.
boolean
removeShutdownHook(Thread hook)
De-register a shutdown hook.
void
runFinalization()
Run finalization on all Objects that are waiting to be finalized.
static void
runFinalizersOnExit(boolean finalizeOnExit)
Deprecated. never rely on finalizers to do a clean, thread-safe, mop-up from your code
long
totalMemory()
Find out how much memory total is available on the heap for allocating Objects.
void
traceInstructions(boolean on)
Tell the VM to trace every bytecode instruction that executes (print out a trace of it).
void
traceMethodCalls(boolean on)
Tell the VM to trace every method call that executes (print out a trace of it).

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

addShutdownHook

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

availableProcessors

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

exec

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 ""

exec

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 ""

exec

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

exec

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

exec

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

exec

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

exit

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

freeMemory

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

gc

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.

getLocalizedInputStream

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

getLocalizedOutputStream

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

getRuntime

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

halt

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

load

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.
Parameters:
filename - the file to load
Throws:
SecurityException - if permission is denied

loadLibrary

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.
Parameters:
libname - the library to load
Throws:
SecurityException - if permission is denied

maxMemory

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

removeShutdownHook

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

runFinalization

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()

runFinalizersOnExit

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()

totalMemory

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

traceInstructions

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

traceMethodCalls

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

Runtime.java -- access to the VM process Copyright (C) 1998, 2002, 2003, 2004, 2005, 2006 Free Software Foundation This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.