The Runtime class provides an interface to the functionality in the runtime library and other process related information.
Most variables of the Runtime class are not public, since they can be accessed by simply inheriting Runtime.
inherits
State supers: Conditions, Constants, stdio
variables
The name of the host on which this program is running.
The name under which this program was invoked (i.e. the basename of argv[0] in C).
The long program name (i.e. argv[0] in C).
The arguments as passed to main.
All the arguments, before any load method modified it.
The environment.
The directory holding the main resources, at least including the character encodings.
The dictionary of classes. Mapping from name to array of classes with that name. Since this is created upon request and it is reset by dynamic loading, it is not publicly available. Access it through the classes_by_name method.
Iff !0, quit (SIGINT, the user interrupt signal) is inhibited.
Iff !0, a signal-int will be raised when quit_inhibit and panic_mode again reach 0.
Iff !0, any signal received (excluding the interrupt signal), other condition signaled or raised, or any object thrown will simply cause an abort. This is used to protect critical sections in the runtime, such as during garbage collection or object allocation. If panic_mode is set, quit_inhibit is implicitly set too.
Iff TRUE, a corefile will be produced on fatal errors, such as uncaught condition raises.
Iff TRUE, a stacktrace will be printed on fatal errors, such as uncaught condition raises. This facility is dependent upon the stacktrace generation being implemented on the platform in use.
The number of objects allocated since the last partial garbage collection run. In this respect, a partial run completing a full run is still considered a partial run.
The number of objects allocated since the previous completed run. This excludes the objects counted by gc_alloc_since_partial; it is adjusted after a run is initiated, before the run is actually started.
Iff TRUE statistics on memory usage and the garbage collector will be emitted upon exit.
Iff TRUE output statistics on the runtime structures at exit.
Iff TRUE output the number of live instances of each class at exit.
Statistics on the garbage collector and allocator, in order: the number of gc runs; the number of runs which complete a full run; the number of object allocated; the number of objects deallocated; the (real, i.e. elapsed) time spent protecting, marking, and sweeping; and the time spent in all of gc (this is the sum of the previous three, plus overhead).
These numbers are only maintained if the runtime library was not instructed to not do so at compile time.
Iff !0, garbage collection won't be run. This is important during, for instance, enumerating a Container, since (most) enumerators can not handle the collection changing while they are enumerating.
Iff TRUE (the default), garbage collection will run atomically, irrespective of the time constraint argument to garbageCollect. When running with atomic garbage collection, new objects are white (presumed dead) whereas with non-atomic garbage collection, new objects are gray (presumably alive).
A program using atomic garbage collection needs less memory, since only one run is needed to reclaim a dead object, instead of two runs. It also means that, for example, in a multi-threaded program, the thread doing garbage collection will block all other threads.
The desired value of gc_atomic, which will take effect after the next GC run. Default is whatever the value of gc_atomic was at startup.
Iff TRUE all garbage will be cleaned upon exit. This is a debugging tool mostly.
The level of debugging garbage output by the garbage collector. Information is output to stderr stream provided by the C library. No information will be output if gc_debug is 0 or if the runtime was not compiled with the appropriate flags.
Threshold for gc_alloc_since_partial before a garbage collection run will be initiated. If gc_partial_threshold is 0, garbage collection is never run implicitly. The default value is 25000, or the value passed as :gc-pth on the command line.
The time allowed for a partial garbage collection run when initiated by gc_alloc_since_partial exceeding gc_partial_threshold. The default is 0, implying no time limit.
When a partial garbage collection run is initiated and gc_alloc_since_total exceeds gc_total_threshold, the gc_partial_time_limit is ignored and instead the gc_total_time_limit is used. If gc_total_threshold is 0, it is ignored.
The time limit used in case the condition described for gc_total_threshold applies.
Iff TRUE, preconditions are checked.
Iff TRUE, postconditions are checked.
Iff TRUE, unhandled signals are printed on [stdio err]. This is for debugging purposes.
methods
int start (All, selector) (object, sel) arguments Array arguments; |
This method is invoked by the runtime library. Its main responsibility is to invoke the real main method, which is identified by the sel and object.
void exit int rc; |
Normal level exit. Cleaning up will be performed.
void fastExit int rc; |
Low level exit. Usual functionality for cleaning up is avoided.
void unhandledSignal Condition condition; |
Output information on the unhandled signal condition on [stdio err].
void willExit int rc; |
Perform all things necessary for a clean exit. This runs the garbage collector if specified by a :gc-exit, dumps gc statistics if specified by :gc-stat, number of instances if specified by :rt-inst, and memory overhead information if specified by :rt-stat.
OutputStream help OutputStream s done MutableKeyed done; |
Output help information about the facilities (most notably `:' arguments) offered by the receiving class, on the OutputStream s.
Any implementation should add itself to the set done, and check for presence before outputting anything, to avoid generating the same output for every subclass not overriding this method.
void load MutableArray arguments; |
Scan the arguments to the program for something telling us whether or how to do certain things.
See the output of :help of any TOM program for short information on the options.
void preload MutableArray arguments; |
Invoked by the runtime library before the first load is invoked.
This method is needed for two occasions: first is to check for :help. The reason this is not done in load is to be able to get some help before any negative side effects of any load method. The second reason is for finding :rt-resource-dir, which must be done before ByteString's load method can play with its encoding.
void reportNumInstances OutputStream s includeZeroes: boolean zeroes = FALSE; |
Output to the stream s the number of live instances for each class. If the optional zeroes is TRUE, classes with zero instances are included in the report. This includes deferred classes, as they cannot have any instances.
protected void runtimeStatistics OutputStream s; |
Output the actual statistics for :rt-stat to the stream s.
Indexed classes; |
Return the array of all class objects.
Mapped classes_by_name; |
Return the, possibly created upon request, mapped collection of classes keyed on their name.
class (State) (class_object) classNamed String name; |
Return the class with the name.
Name may be unqualified, as in "Runtime", which will return the single class with that name, or nil in case such a class does not exist, or if more than one class with that name exists in multiple units.
The name may be qualified, as in "tom.Runtime", in which case the Runtime class of the tom unit will be returned, if that unit and class within that unit exist.
selector selectorNamed String name; |
Return the existing selector known by the name.
boolean selector selector s1 equals selector s2; |
Return TRUE iff the selectors s1 and s2 denote the same selector.
String nameOfSelector selector sel; |
Return the name of the selector.
selector
nullSelector;
|
Return the invalid selector.
void
garbageCollect;
|
Run the garbage collector to the end of a full garbage collection run.
void garbageCollect double time pre gc_atomic -> !time; |
Run the garbage collector for at most time seconds.
void
disableGC
pre
gc_inhibit >= 0
post
gc_inhibit == old gc_inhibit + 1;
|
Increase the gc_inhibit. This invocation should be matched by an invocation of enableGC.
void
enableGC
pre
gc_inhibit > 0
post
gc_inhibit == old gc_inhibit - 1;
|
Decrease the gc_inhibit.
Mapped environment; |
Return the dictionary holding the process environment. The dictionary is filled upon the first request, thread-safely.
ByteString main_resource_dir; |
Return the main_resource_dir.
void setenv (String, String) (environment_variable, value); |
Set the value of the environment_variable, thread-safely.
String hostname; |
Return the hostname of this machine. If the class variable is not set, it is set once from gethostname(2).
String tom_prefix; |
Return the directory in which all TOM stuff has been installed. This returns the value of TOM_PREFIX in the Constants class.
Any perror String prefix for All object class ConditionClass condition_class raise boolean not_signal; |
Construct a Condition for the object with the condition_class and a message created from the (optional) prefix, plus the information available from the (ANSI C) errno variable. If not_signal is TRUE, the new condition is raised; otherwise it is signaled and the result is returned (if a return is allowed).
int
quit_inhibit;
|
Accessor method for quit_inhibit which is private to the Runtime class to protect it against being mutated by subclasses but which can be freely read, hence this method.
void
quit_disable;
|
Increase the quit_inhibit flag. Any increase should be accompanied later on by the corresponding decrease.
void
quit_enable
pre
quit_inhibit > 0;
|
Decrease the quit_inhibit flag, raising a postponsed signal-int if indicated by quit_pending.
int
panic_mode;
|
Accessor method for panic_mode which is private to the Runtime class to protect it against being mutated by subclasses but which can be freely read, hence this method.
void
panic_enable;
|
Increase the panic_mode flag. Any increase should be accompanied later on by the corresponding decrease.
void
panic_disable
pre
panic_mode > 0;
|
Decrease the panic_mode flag, raising a signal-int if requested by quit_pending.
Array crawlStack; |
Return the return addresses currently outstanding on the CPU stack (up to the first 100). Information about these pointers may be obtained from [Runtime symbolInfo].
(ByteString, pointer, ByteString, pointer, pointer) (file_name, base_address, symbol_name, symbol_address, offset) symbolInfo pointer address; |
Return extensive symbol information on the ADDRESS.
void printStack OutputStream stream ignoreUntil: String ignore_until_symbol = ""; |
Print a stack trace to an OutputStream.
The Runtime instance is totally empty.