public class

Runtime

extends Object
java.lang.Object
   ↳ java.lang.Runtime

Class Overview

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

See Also

Summary

Public Methods
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[] 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)
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.
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.
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)
This method is deprecated. Use InputStreamReader.
OutputStream getLocalizedOutputStream(OutputStream stream)
This method is 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.
void loadLibrary(String libName)
Loads and links the library with the specified name.
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)
This method is 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.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public void addShutdownHook (Thread hook)

Since: API Level 1

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

public int availableProcessors ()

Since: API Level 1

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.

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

Since: API Level 1

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.
See Also

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

Since: API Level 1

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.
See Also

public Process exec (String prog)

Since: API Level 1

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.
See Also

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

Since: API Level 1

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.
See Also

public Process exec (String[] progArray)

Since: API Level 1

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.
See Also

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

Since: API Level 1

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.
See Also

public void exit (int code)

Since: API Level 1

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.
See Also

public long freeMemory ()

Since: API Level 1

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

Returns
  • the approximate amount of free memory, measured in bytes.

public void gc ()

Since: API Level 1

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.

public InputStream getLocalizedInputStream (InputStream stream)

Since: API Level 1

This method is 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.

public OutputStream getLocalizedOutputStream (OutputStream stream)

Since: API Level 1

This method is 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.

public static Runtime getRuntime ()

Since: API Level 1

Returns the single Runtime instance.

Returns
  • the Runtime object for the current application.

public void halt (int code)

Since: API Level 1

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.
See Also

public void load (String pathName)

Since: API Level 1

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.
See Also

public void loadLibrary (String libName)

Since: API Level 1

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.
See Also

public long maxMemory ()

Since: API Level 1

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.

public boolean removeShutdownHook (Thread hook)

Since: API Level 1

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

public void runFinalization ()

Since: API Level 1

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

public static void runFinalizersOnExit (boolean run)

Since: API Level 1

This method is 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.

public long totalMemory ()

Since: API Level 1

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

Returns
  • the total amount of memory, measured in bytes.

public void traceInstructions (boolean enable)

Since: API Level 1

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.

public void traceMethodCalls (boolean enable)

Since: API Level 1

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

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