java.lang
Class Runtime

java.lang.Object
  java.lang.Runtime

public class Runtime
extends Object

Allows Java applications to interface with the environment in which they are running. Applications can not create an instance of this class, but they can get a singleton instance by invoking getRuntime().

Since:

Android 1.0

See Also:

System

Method Summary

void	addShutdownHook(Thread hook) Registers a virtual-machine shutdown hook.
int	availableProcessors() Returns the number of processors available to the virtual machine.
Process	exec(String prog) Executes the specified program in a separate native process.
Process	exec(String[] progArray) Executes the specified command and its arguments in a separate native process.
Process	exec(String[] progArray, String[] envp) Executes the specified command and its arguments in a separate native process.
Process	exec(String[] progArray, String[] envp, File directory) Executes the specified command and its arguments in a separate native process.
Process	exec(String prog, String[] envp) Executes the specified program in a separate native process.
Process	exec(String prog, String[] envp, File directory) Executes the specified program in a separate native process.
void	exit(int code) Causes the virtual machine to stop running and the program to exit.
long	freeMemory() Returns the amount of free memory resources which are available to the running program.
void	gc() Indicates to the virtual machine that it would be a good time to run the garbage collector.
InputStream	getLocalizedInputStream(InputStream stream) Deprecated. Use InputStreamReader.
OutputStream	getLocalizedOutputStream(OutputStream stream) Deprecated. Use OutputStreamWriter.
static Runtime	getRuntime() Returns the single Runtime instance.
void	halt(int code) Causes the virtual machine to stop running, and the program to exit.
void	load(String pathName) Loads and links the dynamic library that is identified through the specified path.
(package private) void	load(String filename, ClassLoader loader)
void	loadLibrary(String libName) Loads and links the library with the specified name.
(package private) void	loadLibrary(String libname, ClassLoader loader)
long	maxMemory() Returns the maximum amount of memory that may be used by the virtual machine, or Long.MAX_VALUE if there is no such limit.
boolean	removeShutdownHook(Thread hook) Unregisters a previously registered virtual machine shutdown hook.
void	runFinalization() Provides a hint to the virtual machine that it would be useful to attempt to perform any outstanding object finalizations.
static void	runFinalizersOnExit(boolean run) Deprecated. This method is unsafe.
long	totalMemory() Returns the total amount of memory which is available to the running program.
void	traceInstructions(boolean enable) Switches the output of debug information for instructions on or off.
void	traceMethodCalls(boolean enable) Switches the output of debug information for methods on or off.

Methods inherited from class java.lang.Object

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

Method Detail

exec

public Process exec(String[] progArray)
             throws IOException

Executes the specified command and its arguments in a separate native process. The new process inherits the environment of the caller. Calling this method is equivalent to calling exec(progArray, null, null).

Parameters:

progArray - the array containing the program to execute as well as any arguments to the program.

Returns:

the new Process object that represents the native process.

Throws:

IOException - if the requested program can not be executed.

SecurityException - if the current SecurityManager disallows program execution.

Since:

Android 1.0

See Also:

SecurityManager.checkExec(java.lang.String)

exec

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

Executes the specified command and its arguments in a separate native process. The new process uses the environment provided in envp. Calling this method is equivalent to calling exec(progArray, envp, null).

Parameters:

progArray - the array containing the program to execute as well as any arguments to the program.

envp - the array containing the environment to start the new process in.

Returns:

the new Process object that represents the native process.

Throws:

IOException - if the requested program can not be executed.

SecurityException - if the current SecurityManager disallows program execution.

Since:

Android 1.0

See Also:

SecurityManager.checkExec(java.lang.String)

exec

public Process exec(String[] progArray,
                    String[] envp,
                    File directory)
             throws IOException

Executes the specified command and its arguments in a separate native process. The new process uses the environment provided in envp and the working directory specified by directory.

Parameters:

progArray - the array containing the program to execute as well as any arguments to the program.

envp - the array containing the environment to start the new process in.

directory - the directory in which to execute the program. If null, execute if in the same directory as the parent process.

Returns:

the new Process object that represents the native process.

Throws:

IOException - if the requested program can not be executed.

SecurityException - if the current SecurityManager disallows program execution.

Since:

Android 1.0

See Also:

SecurityManager.checkExec(java.lang.String)

exec

public Process exec(String prog)
             throws IOException

Executes the specified program in a separate native process. The new process inherits the environment of the caller. Calling this method is equivalent to calling exec(prog, null, null).

Parameters:

prog - the name of the program to execute.

Returns:

the new Process object that represents the native process.

Throws:

IOException - if the requested program can not be executed.

SecurityException - if the current SecurityManager disallows program execution.

Since:

Android 1.0

See Also:

SecurityManager.checkExec(java.lang.String)

exec

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

Executes the specified program in a separate native process. The new process uses the environment provided in envp. Calling this method is equivalent to calling exec(prog, envp, null).

Parameters:

prog - the name of the program to execute.

envp - the array containing the environment to start the new process in.

Returns:

the new Process object that represents the native process.

Throws:

IOException - if the requested program can not be executed.

SecurityException - if the current SecurityManager disallows program execution.

Since:

Android 1.0

See Also:

SecurityManager.checkExec(java.lang.String)

exec

public Process exec(String prog,
                    String[] envp,
                    File directory)
             throws IOException

Executes the specified program in a separate native process. The new process uses the environment provided in envp and the working directory specified by directory.

Parameters:

prog - the name of the program to execute.

envp - the array containing the environment to start the new process in.

directory - the directory in which to execute the program. If null, execute if in the same directory as the parent process.

Returns:

the new Process object that represents the native process.

Throws:

IOException - if the requested program can not be executed.

SecurityException - if the current SecurityManager disallows program execution.

Since:

Android 1.0

See Also:

SecurityManager.checkExec(java.lang.String)

exit

public void exit(int code)

Causes the virtual machine to stop running and the program to exit. If runFinalizersOnExit(boolean) has been previously invoked with a true argument, then all all objects will be properly garbage-collected and finalized first.

Parameters:

code - the return code. By convention, non-zero return codes indicate abnormal terminations.

Throws:

SecurityException - if the current SecurityManager does not allow the running thread to terminate the virtual machine.

Since:

Android 1.0

See Also:

SecurityManager.checkExit(int)

freeMemory

public long freeMemory()

Returns the amount of free memory resources which are available to the running program.

Returns:

the approximate amount of free memory, measured in bytes.

Since:

Android 1.0

gc

public void gc()

Indicates to the virtual machine that it would be a good time to run the garbage collector. Note that this is a hint only. There is no guarantee that the garbage collector will actually be run.

Since:

Android 1.0

getRuntime

public static Runtime getRuntime()

Returns the single Runtime instance.

Returns:

the Runtime object for the current application.

Since:

Android 1.0

load

public void load(String pathName)

Loads and links the dynamic library that is identified through the specified path. This method is similar to loadLibrary(String), but it accepts a full path specification whereas loadLibrary just accepts the name of the library to load.

Parameters:

pathName - the absolute (platform dependent) path to the library to load.

Throws:

UnsatisfiedLinkError - if the library can not be loaded.

SecurityException - if the current SecurityManager does not allow to load the library.

Since:

Android 1.0

See Also:

SecurityManager.checkLink(java.lang.String)

load

void load(String filename,
          ClassLoader loader)

loadLibrary

public void loadLibrary(String libName)

Loads and links the library with the specified name. The mapping of the specified library name to the full path for loading the library is implementation-dependent.

Parameters:

libName - the name of the library to load.

Throws:

UnsatisfiedLinkError - if the library can not be loaded.

SecurityException - if the current SecurityManager does not allow to load the library.

Since:

Android 1.0

See Also:

SecurityManager.checkLink(java.lang.String)

loadLibrary

void loadLibrary(String libname,
                 ClassLoader loader)

runFinalization

public void runFinalization()

Provides a hint to the virtual machine that it would be useful to attempt to perform any outstanding object finalizations.

Since:

Android 1.0

runFinalizersOnExit

@Deprecated
public static void runFinalizersOnExit(boolean run)

Deprecated. This method is unsafe.

Sets the flag that indicates whether all objects are finalized when the virtual machine is about to exit. Note that all finalization which occurs when the system is exiting is performed after all running threads have been terminated.

Parameters:

run - true to enable finalization on exit, false to disable it.

Since:

Android 1.0

totalMemory

public long totalMemory()

Returns the total amount of memory which is available to the running program.

Returns:

the total amount of memory, measured in bytes.

Since:

Android 1.0

traceInstructions

public void traceInstructions(boolean enable)

Switches the output of debug information for instructions on or off. For the Android 1.0 reference implementation, this method does nothing.

Parameters:

enable - true to switch tracing on, false to switch it off.

Since:

Android 1.0

traceMethodCalls

public void traceMethodCalls(boolean enable)

Switches the output of debug information for methods on or off.

Parameters:

enable - true to switch tracing on, false to switch it off.

Since:

Android 1.0

getLocalizedInputStream

@Deprecated
public InputStream getLocalizedInputStream(InputStream stream)

Deprecated. Use InputStreamReader.

Returns the localized version of the specified input stream. The input stream that is returned automatically converts all characters from the local character set to Unicode after reading them from the underlying stream.

Parameters:

stream - the input stream to localize.

Returns:

the localized input stream.

Since:

Android 1.0

getLocalizedOutputStream

@Deprecated
public OutputStream getLocalizedOutputStream(OutputStream stream)

Deprecated. Use OutputStreamWriter.

Returns the localized version of the specified output stream. The output stream that is returned automatically converts all characters from Unicode to the local character set before writing them to the underlying stream.

Parameters:

stream - the output stream to localize.

Returns:

the localized output stream.

Since:

Android 1.0

addShutdownHook

public void addShutdownHook(Thread hook)

Registers a virtual-machine shutdown hook. A shutdown hook is a Thread that is ready to run, but has not yet been started. All registered shutdown hooks will be executed once the virtual machine shuts down properly. A proper shutdown happens when either the exit(int) method is called or the surrounding system decides to terminate the application, for example in response to a CTRL-C or a system-wide shutdown. A termination of the virtual machine due to the halt(int) method, an Error or a SIGKILL, in contrast, is not considered a proper shutdown. In these cases the shutdown hooks will not be run.

Shutdown hooks are run concurrently and in an unspecified order. Hooks failing due to an unhandled exception are not a problem, but the stack trace might be printed to the console. Once initiated, the whole shutdown process can only be terminated by calling halt().

If runFinalizersOnExit(boolean) has been called with a true argument, garbage collection and finalization will take place after all hooks are either finished or have failed. Then the virtual machine terminates.

It is recommended that shutdown hooks do not do any time-consuming activities, in order to not hold up the shutdown process longer than necessary.

Parameters:

hook - the shutdown hook to register.

Throws:

IllegalArgumentException - if the hook has already been started or if it has already been registered.

IllegalStateException - if the virtual machine is already shutting down.

SecurityException - if a SecurityManager is registered and the calling code doesn't have the RuntimePermission("shutdownHooks").

removeShutdownHook

public boolean removeShutdownHook(Thread hook)

Unregisters a previously registered virtual machine shutdown hook.

Parameters:

hook - the shutdown hook to remove.

Returns:

true if the hook has been removed successfully; false otherwise.

Throws:

IllegalStateException - if the virtual machine is already shutting down.

SecurityException - if a SecurityManager is registered and the calling code doesn't have the RuntimePermission("shutdownHooks").

halt

public void halt(int code)

Causes the virtual machine to stop running, and the program to exit. Neither shutdown hooks nor finalizers are run before.

Parameters:

code - the return code. By convention, non-zero return codes indicate abnormal terminations.

Throws:

SecurityException - if the current SecurityManager does not allow the running thread to terminate the virtual machine.

Since:

Android 1.0

See Also:

SecurityManager.checkExit(int), addShutdownHook(Thread), removeShutdownHook(Thread), runFinalizersOnExit(boolean)

availableProcessors

public int availableProcessors()

Returns the number of processors available to the virtual machine. The Android reference implementation (currently) always returns 1.

Returns:

the number of available processors, at least 1.

Since:

Android 1.0

maxMemory

public long maxMemory()

Returns the maximum amount of memory that may be used by the virtual machine, or Long.MAX_VALUE if there is no such limit.

Returns:

the maximum amount of memory that the virtual machine will try to allocate, measured in bytes.

Since:

Android 1.0