Runtime

Overview

Package

Class

Use

Deprecated

Index

Home >> All >> java >> [ lang overview ]

PREV CLASS NEXT CLASS

SUMMARY:

JAVADOC |

SOURCE |

DOWNLOAD | NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

java.lang
Class Runtime

java.lang.Object
  java.lang.Runtime

public class Runtime
extends Object

Runtime represents the Virtual Machine.

Field Summary

private static Runtime current
          The one and only runtime instance.

private Thread exitSequence
          The thread that started the exit sequence.

private String[] libpath
          The library path, to search when loading libraries.

private java.util.Set shutdownHooks
          All shutdown hooks.

Constructor Summary

private Runtime()
          Not instantiable by a user, this should only create one instance.

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[] 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, java.io.File dir)
          Create a new subprocess with the specified command line, already tokenized, and the specified environment and working directory.

Process exec(String cmdline, String[] env)
          Create a new subprocess with the specified command line and environment.

Process exec(String cmdline, String[] env, java.io.File dir)
          Create a new subprocess with the specified command line, 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.

java.io.InputStream getLocalizedInputStream(java.io.InputStream in)
          Deprecated. InputStreamReader is the preferred way to read local encodings

java.io.OutputStream getLocalizedOutputStream(java.io.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.

(package private) void load(String filename, ClassLoader loader)
          Same as load(String) but using the given loader.

private static int loadLib(String filename, ClassLoader loader)
          Do a security check on the filename and then load the native library.

void loadLibrary(String libname)
          Load a native library using a system-independent "short name" for the library.

(package private) void loadLibrary(String libname, ClassLoader loader)
          Same as loadLibrary(String) but using the given loader.

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

(package private) boolean runShutdownHooks()
          On first invocation, run all the shutdown hooks and return true.

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, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

libpath

private final String[] libpath

The library path, to search when loading libraries. We can also safely use this as a lock for synchronization.

exitSequence

private Thread exitSequence

The thread that started the exit sequence. Access to this field must be thread-safe; lock on libpath to avoid deadlock with user code. runFinalization() may want to look at this to see if ALL finalizers should be run, because the virtual machine is about to halt.

shutdownHooks

private java.util.Set shutdownHooks

All shutdown hooks. This is initialized lazily, and set to null once all shutdown hooks have run. Access to this field must be thread-safe; lock on libpath to avoid deadlock with user code.

current

private static final Runtime current

The one and only runtime instance.

Constructor Detail

Runtime

private Runtime()

Not instantiable by a user, this should only create one instance.

Method Detail

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.

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.

runShutdownHooks

boolean runShutdownHooks()

On first invocation, run all the shutdown hooks and return true. Any subsequent invocations will simply return false. Note that it is package accessible so that VMRuntime can call it when VM exit is not triggered by a call to Runtime.exit().

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.

Since:: 1.3

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

Since:: 1.3

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

Since:: 1.3

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

Since:: 1.1

exec

public Process exec(String cmdline)
             throws java.io.IOException

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

exec

public Process exec(String cmdline,
                    String[] env)
             throws java.io.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.

exec

public Process exec(String cmdline,
                    String[] env,
                    java.io.File dir)
             throws java.io.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.

Since:: 1.3

exec

public Process exec(String[] cmd)
             throws java.io.IOException

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

exec

public Process exec(String[] cmd,
                    String[] env)
             throws java.io.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.

exec

public Process exec(String[] cmd,
                    String[] env,
                    java.io.File dir)
             throws java.io.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.

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.

freeMemory

public long freeMemory()

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

totalMemory

public long totalMemory()

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

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!).

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.

runFinalization

public void runFinalization()

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

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.

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.

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.

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

load

void load(String filename,
          ClassLoader loader)

Same as load(String) but using the given loader.

loadLib

private static int loadLib(String filename,
                           ClassLoader loader)

Do a security check on the filename and then load the native library.

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.

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.

loadLibrary

void loadLibrary(String libname,
                 ClassLoader loader)

Same as loadLibrary(String) but using the given loader.

getLocalizedInputStream

public java.io.InputStream getLocalizedInputStream(java.io.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.

getLocalizedOutputStream

public java.io.OutputStream getLocalizedOutputStream(java.io.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.

Overview

Package

Class

Use

Deprecated

Index

Home >> All >> java >> [ lang overview ]

PREV CLASS NEXT CLASS

SUMMARY:

JAVADOC |

SOURCE |

DOWNLOAD | NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Field Summary
`private static Runtime`	`current` The one and only runtime instance.
`private Thread`	`exitSequence` The thread that started the exit sequence.
`private String[]`	`libpath` The library path, to search when loading libraries.
`private java.util.Set`	`shutdownHooks` All shutdown hooks.

Constructor Summary
`private`	`Runtime()` Not instantiable by a user, this should only create one instance.

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[] 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, java.io.File dir)` Create a new subprocess with the specified command line, already tokenized, and the specified environment and working directory.
`Process`	`exec(String cmdline, String[] env)` Create a new subprocess with the specified command line and environment.
`Process`	`exec(String cmdline, String[] env, java.io.File dir)` Create a new subprocess with the specified command line, 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.
`java.io.InputStream`	`getLocalizedInputStream(java.io.InputStream in)` Deprecated. `InputStreamReader` is the preferred way to read local encodings
`java.io.OutputStream`	`getLocalizedOutputStream(java.io.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.
`(package private) void`	`load(String filename, ClassLoader loader)` Same as `load(String)` but using the given loader.
`private static int`	`loadLib(String filename, ClassLoader loader)` Do a security check on the filename and then load the native library.
`void`	`loadLibrary(String libname)` Load a native library using a system-independent "short name" for the library.
`(package private) void`	`loadLibrary(String libname, ClassLoader loader)` Same as `loadLibrary(String)` but using the given loader.
`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
`(package private) boolean`	`runShutdownHooks()` On first invocation, run all the shutdown hooks and return true.
`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).

java.lang Class Runtime

libpath

exitSequence

shutdownHooks

current

Runtime

getRuntime

exit

runShutdownHooks

addShutdownHook

removeShutdownHook

halt

runFinalizersOnExit

exec

exec

exec

exec

exec

exec

availableProcessors

freeMemory

totalMemory

maxMemory

gc

runFinalization

traceInstructions

traceMethodCalls

load

load

loadLib

loadLibrary

loadLibrary

getLocalizedInputStream

getLocalizedOutputStream

java.lang
Class Runtime