java.lang
Class Runtime

java.lang.Object
  java.lang.Runtime

public class Runtime
extends Object

Runtime provides control over the runtime system, i.e., memory management, VM termination cleanup, execution of external commands, etc.

Since:

1.0

Constructor Summary

Runtime()

Method Summary

void	addShutdownHook(Thread hook) add a shutdown hook adds a shutdown hook that will be started on a call to exit(int).
int	availableProcessors() Returns the number of processors available to the Java Virtual machine.
Process	exec(String command) Creates a new process to execute an external command with given environment and current directory.
Process	exec(String[] cmdarray) Creates a new process to execute an external command with given environment and current directory.
Process	exec(String[] cmdarray, String[] envp) Creates a new process to execute an external command with given environment and current directory.
Process	exec(String[] cmdarray, String[] envp, File dir)
Process	exec(String command, String[] envp) Creates a new process to execute an external command with given environment and current directory.
Process	exec(String command, String[] envp, File dir) Creates a new process to execute an external command with given environment and current directory.
void	exit(int status) exit terminates the currently running Java application and the VM.
long	freeMemory() freeMemory returns the amount of free memory in bytes.
void	gc() gc indicates to the VM that it may be a good time to run the garbage collector.
InputStream	getLocalizedInputStream(InputStream in) Deprecated. since 1.1, class InputStreamReader is available for converting the encoding.
OutputStream	getLocalizedOutputStream(OutputStream out) Deprecated. since 1.1, class OutputStreamWriter is available for converting the encoding.
static Runtime	getRuntime() getRuntime returns the singleton instance of this class.
void	halt(int status) halt terminates the currently running Java application and the VM without running shutdown hooks.
void	load(String filename) load a library or system file.
void	loadLibrary(String libname) loadLibrary loads a system library with the given name into the system.
long	maxMemory() maxMemory returns the maximum amount of memory that the virtual machine will attempt to use.
boolean	removeShutdownHook(Thread hook) remove a shutdown hook that was registered using addShutdownHook.
void	runFinalization() runFinalization runs the finalize() method of all objects that are pending for finalization.
static void	runFinalizersOnExit(boolean value) Deprecated. running the finalizers is unsafe, therefore this method is deprecated.
long	totalMemory() totalMemory returns the total size of the memory in bytes.
void	traceInstructions(boolean on) Enable/disable tracing of executed instructions.
void	traceMethodCalls(boolean on) Enable/disable tracing of method calls.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Runtime

public Runtime()

Method Detail

freeMemory

public long freeMemory()

freeMemory returns the amount of free memory in bytes.

Note that the free memory does not include memory that is no used by the application any longer, but that has not been reclaimed by the GC yet. For JamaicaVM, the GC usually reclaimes unused memory late as long as there is sufficient free memory available. For a more accurate result, on or several calls to gc() and runFinalization() may be used before the call to freeMemory().

For JamaicaVM, the returned value is the free memory that is directly usable for Java objects, i.e., memory needed by the memory management system for bookkeeping is not included.

Returns:

the currently free memory.

totalMemory

public long totalMemory()

totalMemory returns the total size of the memory in bytes.

For JamaicaVM, the returned value is the memory that is directly usable for Java objects, i.e., memory needed by the memory management system for bookkeeping is not included.

Returns:

the current size of the heap.

gc

public void gc()

gc indicates to the VM that it may be a good time to run the garbage collector.

For JamaicaVM, a call to Runtime.gc() will perform at least one full garbage collection cycle and at most two full garbage collection cycles. A call to gc() may therefore require a significant amount of time.

Note that running the garbage collector alone does not ensure that memory that is occupied by objects that have a finalize() method will be reclaimed: Their memory will be held until the finalize() method has been executed and the object is found to be unreachable after a second GC cycle. To ensure that all finalizers are executed and the memory of finalized objects is freed, three calls are required as follows:

   Runtime.getRuntime().gc();  // find garbage
   Runtime.getRuntime().runFinalization(); // execute finalizers
   Runtime.getRuntime().gc();  // recycle finalized objects.
 

Any weak, soft or phantom references used in JamaicaVM will be updated also via the runFinalization(), i.e., an object to which a weak, soft or phantom reference exist can only be reclaimed when runFinalization() is called either by the finalizer thread or by an application thread,

To increase the overall system performance, it may be wise to run a low-priority thread that calls gc() and runFinalization() perpetually:

   while (true)
     {
       Runtime.getRuntime().gc();
       Runtime.getRuntime().runFinalization();
     }
 

This will use all free CPU time to keep the amount of allocated memory as low as possible, such that memory allocation overhead for all higher-priority threads is minimized.

maxMemory

public long maxMemory()

maxMemory returns the maximum amount of memory that the virtual machine will attempt to use.

For JamaicaVM, this is either the same as totalMemory if the heap size is not dynamic, else it is the maximum size to which the heap size may grow (the builder argument -maxHeapSize, -maxHeapSizeFromEnv or the VM environment variable JAMAICAVM_MAXHEAPSIZE).

Returns:

the maximum heap size, Long.MAX_VALUE if not limited.

Since:

1.4

availableProcessors

public int availableProcessors()

Returns the number of processors available to the Java Virtual machine.

For standard JamaicaVM, this method always returns 1. Even on a multi-processor system, JamaicaVM uses at most one processor to execute Java code. This might change in future releases.

For the parallel JamaicaVM (builder option -parallel, of command jamaicavmm), this gives the number of CPUs available to the VM for parallel execution of Java threads.

ensures

   (result >= 1);
 

Returns:

the number of processors available to the virtual machine.

Since:

1.4

getRuntime

public static Runtime getRuntime()

getRuntime returns the singleton instance of this class.

Returns:

the Runtime instance, never null.

Throws:

InternalError - for JamaicaVM, if this is called early during system initialization before Runtime instance was created.

exit

public void exit(int status)

exit terminates the currently running Java application and the VM. It runs the shutdown hooks and exits the VM.

Parameters:

status - exit status, 0 for ok.

Throws:

SecurityException - if a security manager is installed and its checkExit(status) method throws this exception.

halt

public void halt(int status)

halt terminates the currently running Java application and the VM without running shutdown hooks.

Parameters:

status - exit status, 0 for ok.

Throws:

SecurityException - if a security manager is installed and its checkExit(status) method throws this exception.

Since:

1.3

addShutdownHook

public void addShutdownHook(Thread hook)

add a shutdown hook adds a shutdown hook that will be started on a call to exit(int). Shutdown hooks must execute quickly and should not block if possible. Shutdown hooks will be executed in parallel, i.e., no shutdown hook may rely on any other resource that may be freed by another shutdown hook.

Parameters:

hook - the shutdown hook, must not be null and must not be or have been started.

Throws:

SecurityManager - if a security manager sm is installed and a call to sm.checkPermission( new RuntimePermission( "shutdownHooks" )) causes this exception.

IllegalArgumentException - if hook has already been added or if hook has already been started.

IllegalStateException - if the VM is currently shutting down.

Since:

1.3

removeShutdownHook

public boolean removeShutdownHook(Thread hook)

remove a shutdown hook that was registered using addShutdownHook.

Parameters:

hook - hook the shutdown hook, must not be null.

Throws:

SecurityManager - if a security manager sm is installed and a call to sm.checkPermission( new RuntimePermission( "shutdownHooks" )) causes this exception.

IllegalStateException - if the VM is currently shutting down.

Since:

1.3

runFinalizersOnExit

public static void runFinalizersOnExit(boolean value)

Deprecated. running the finalizers is unsafe, therefore this method is deprecated.

Set flag if finalizers should be run in exit of the JVM.

For JamaicaVM, the finalizer of boot classes are not run even if this routine was called with a true argument. The reason is that these finalizers would do things like closing System.out, which would make it very hard to do anything useful afterwards.

Parameters:

value - flag

Throws:

SecurityException - if a security manager is installed and its checkExit(0) method throws this exception.

Since:

1.1

exec

public Process exec(String command)
             throws IOException

Creates a new process to execute an external command with given environment and current directory.

If a security manager is installed, its checkExec() method will be called with the command array as an argument.

This is a short form for exec(command,null).

Parameters:

command - the command and its arguments. This will be parsed by a StringTokenizer and passed to exec(String[],String[],File).

Returns:

process object

Throws:

IOException - if an error during execution occurred. The kinds of errors that may occur are system-dependent.

SecurityException - if a security manager sm is installed and sm.checkExec(cmdarray) throws this exception.

NullPointerException - if cmdarray==null or any element of cmdarray is null.

IllegalArgumentException - if command contains no tokens.

Since:

1.3

exec

public Process exec(String command,
                    String[] envp)
             throws IOException

Creates a new process to execute an external command with given environment and current directory.

If a security manager is installed, its checkExec() method will be called with the command array as an argument.

This is a short form for exec(command,envp,null).

Parameters:

command - the command and its arguments. This will be parsed by a StringTokenizer and passed to exec(String[],String[],File).

envp - environment variables, null to use the current environment.

Returns:

process object

Throws:

IOException - if an error during execution occurred. The kinds of errors that may occur are system-dependent.

SecurityException - if a security manager sm is installed and sm.checkExec(cmdarray) throws this exception.

NullPointerException - if cmdarray==null or any element of cmdarray is null or envp is non-null and any element of envp is null.

IllegalArgumentException - if command contains no tokens.

Since:

1.3

exec

public Process exec(String command,
                    String[] envp,
                    File dir)
             throws IOException

Creates a new process to execute an external command with given environment and current directory.

If a security manager is installed, its checkExec() method will be called with the command array as an argument.

Parameters:

command - the command and its arguments. This will be parsed by a StringTokenizer and passed to exec(String[],String[],File).

envp - environment variables, null to use the current environment.

dir - the current directory to be used for the new process, null to inherit the current directory from this process.

Returns:

process object

Throws:

IOException - if an error during execution occurred. The kinds of errors that may occur are system-dependent.

SecurityException - if a security manager sm is installed and sm.checkExec(cmdarray) throws this exception.

NullPointerException - if cmdarray==null or any element of cmdarray is null or envp is non-null and any element of envp is null.

IllegalArgumentException - if command contains no tokens.

Since:

1.3

exec

public Process exec(String[] cmdarray)
             throws IOException

Creates a new process to execute an external command with given environment and current directory.

If a security manager is installed, its checkExec() method will be called with the command array as an argument.

This is a short form for exec(cmdarray,null).

Parameters:

cmdarray - command array with the command and arguments of the command line.

Returns:

process object

Throws:

IOException - if an error during execution occurred. The kinds of errors that may occur are system-dependent.

SecurityException - if a security manager sm is installed and sm.checkExec(cmdarray) throws this exception.

NullPointerException - if cmdarray==null or any element of cmdarray is null.

IndexOutOfBoundsException - if cmdarray.length==0.

Since:

1.3

exec

public Process exec(String[] cmdarray,
                    String[] envp)
             throws IOException

Creates a new process to execute an external command with given environment and current directory.

If a security manager is installed, its checkExec() method will be called with the command array as an argument.

This is a short form for exec(cmdarray,envp,null).

Parameters:

cmdarray - command array with the command and arguments of the command line.

envp - environment variables, null to use the current environment.

Returns:

process object

Throws:

IOException - if an error during execution occurred. The kinds of errors that may occur are system-dependent.

SecurityException - if a security manager sm is installed and sm.checkExec(cmdarray) throws this exception.

NullPointerException - if cmdarray==null or any element of cmdarray is null or envp is non-null and any element of envp is null.

IndexOutOfBoundsException - if cmdarray.length==0.

Since:

1.3

exec

public Process exec(String[] cmdarray,
                    String[] envp,
                    File dir)
             throws IOException

Throws:

IOException

runFinalization

public void runFinalization()

runFinalization runs the finalize() method of all objects that are pending for finalization. The finalize methods will be executed within the current thread.

Running the finalizers will permit the garbage collector to reclaim the memory occupied by these objects. However, the memory cannot be reclaimed immediately after execution of finalize(). Instead, since finalize() may have made the object reachable again, the garbage collector first has to show that no new references to the object have been generated. So in the worst case, the garbage collector needs to complete a full GC cycle before the memory can be reclaimed.

In JamaicaVM, runFinalization is wrapped into HeapMemory.executeInArea(), such that it can be called from scoped or immortal memory as well.

traceInstructions

public void traceInstructions(boolean on)

Enable/disable tracing of executed instructions.

The java specification does not specify what information should be collected or where it should be put. It actually allows Implementations to ignore this method completely.

NOTE: In JamaicaVM, this method does nothing.

Parameters:

on - flag to indicate whether tracing should be enabled (true) or disabled (false) trace instructions.

traceMethodCalls

public void traceMethodCalls(boolean on)

Enable/disable tracing of method calls.

The java specification does not specify what information should be collected or where it should be put. It actually allows Implementations to ignore this method completely.

NOTE: In JamaicaVM, this method does nothing.

Parameters:

on - flag to indicate whether tracing should be enabled (true) or disabled (false) trace instructions.

load

public void load(String filename)

load a library or system file.

If a security manager sm is installed, sm.checkLink(filename) is called to check the permission to load this library.

Repeated attempts to load the same library will have not effect.

Parameters:

filename - absolute pathname of the library to loaded.

Throws:

NullPointerException - if filename is null

UnsatisfiedLinkError - if the library could not be loaded from the specified file.

SecurityException - if a security manager sm is installed and sm.checkLink(filename) throws this exception.

loadLibrary

public void loadLibrary(String libname)

loadLibrary loads a system library with the given name into the system. The place where library are loaded from (e.g., the library path) and the exact file name (pre- and suffixes etc.) are system dependent.

If a security manager sm is installed, sm.checkLink(filename) is called to check the permission to load this library.

Repeated calls of this method have no effect, any library is loaded only once.

Parameters:

libname - the library name, excluding path, suffix etc.

Throws:

NullPointerException - if libname is null

UnsatisfiedLinkError - if the library with the specified name could not be loaded.

SecurityException - if a security manager sm is installed and sm.checkLink(libname) throws this exception.

getLocalizedInputStream

public InputStream getLocalizedInputStream(InputStream in)

Deprecated. since 1.1, class InputStreamReader is available for converting the encoding.

Get an input stream that translates the local encoding into Unicode characters.

Parameters:

in - the original input stream.

Returns:

the localized input stream. The current implementation for JamaicaVM always returns in.

getLocalizedOutputStream

public OutputStream getLocalizedOutputStream(OutputStream out)

Deprecated. since 1.1, class OutputStreamWriter is available for converting the encoding.

Get an output stream that translates unicode characters to the local encoding.

Parameters:

out - the original output stream.

Returns:

the localized output stream. The current implementation for JamaicaVM always returns out.