8.64. File tom/Runtime

class tom.Runtime

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.


State supers: Conditions, Constants, stdio


static String hostname;

The name of the host on which this program is running.

static public String program_name;

The name under which this program was invoked (i.e. the basename of argv[0] in C).

static public String long_program_name;

The long program name (i.e. argv[0] in C).

static Array arguments;

The arguments as passed to main.

static Array all_arguments;

All the arguments, before any load method modified it.

static Mapped environment;

The environment.

static private ByteString main_resource_dir;

The directory holding the main resources, at least including the character encodings.

static private MutableMapped classes_by_name;

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.

static private int quit_inhibit;

Iff !0, quit (SIGINT, the user interrupt signal) is inhibited.

static boolean quit_pending;

Iff !0, a signal-int will be raised when quit_inhibit and panic_mode again reach 0.

static int panic_mode;

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.

static boolean core_on_fatal;

Iff TRUE, a corefile will be produced on fatal errors, such as uncaught condition raises.

static boolean stacktrace_on_fatal;

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.

static int gc_alloc_since_partial;

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.

static int gc_alloc_since_total;

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.

static boolean gc_stat_at_exit;

Iff TRUE statistics on memory usage and the garbage collector will be emitted upon exit.

static boolean rt_stat_at_exit;

Iff TRUE output statistics on the runtime structures at exit.

static boolean rt_num_inst_at_exit;

Iff TRUE output the number of live instances of each class at exit.

static int gc_num_runs;

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

static int gc_num_complete;

static long gc_num_alloc;

static long gc_num_dealloc;

static double gc_total_protect;

static double gc_total_mark;

static double gc_total_sweep;

static double gc_total_all;

static int malloc_cur_bytes;

These numbers are only maintained if the runtime library was not instructed to not do so at compile time.

static int malloc_max_bytes;

static int malloc_cum_bytes;

static int malloc_cur_items;

static int malloc_max_items;

static int malloc_cum_items;

static int gc_inhibit;

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.

static private boolean gc_atomic;

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.

static boolean gc_atomic_next;

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.

static boolean gc_full_at_exit;

Iff TRUE all garbage will be cleaned upon exit. This is a debugging tool mostly.

static int gc_debug;

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.

static int gc_partial_threshold;

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.

static double gc_partial_time_limit;

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.

static int gc_total_threshold;

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.

static double gc_total_time_limit;

The time limit used in case the condition described for gc_total_threshold applies.

static boolean preconditions_enabled;

Iff TRUE, preconditions are checked.

static boolean postconditions_enabled;

Iff TRUE, postconditions are checked.

static boolean rt_print_signals;

Iff TRUE, unhandled signals are printed on [stdio err]. This is for debugging purposes.


      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.

  exit int rc;

Normal level exit. Cleaning up will be performed.

  fastExit int rc;

Low level exit. Usual functionality for cleaning up is avoided.

  unhandledSignal Condition condition;

Output information on the unhandled signal condition on [stdio err].

  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.

  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.

  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.

  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.

  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.


Return the array of all class objects.


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.

  selectorNamed String name;

Return the existing selector known by the name.

  selector selector s1
    equals selector s2;

Return TRUE iff the selectors s1 and s2 denote the same selector.

  nameOfSelector selector sel;

Return the name of the selector.


Return the invalid selector.


Run the garbage collector to the end of a full garbage collection run.

  garbageCollect double time
  gc_atomic -> !time;

Run the garbage collector for at most time seconds.

  gc_inhibit >= 0
  gc_inhibit == old gc_inhibit + 1;

Increase the gc_inhibit. This invocation should be matched by an invocation of enableGC.

  gc_inhibit > 0
  gc_inhibit == old gc_inhibit - 1;

Decrease the gc_inhibit.


Return the dictionary holding the process environment. The dictionary is filled upon the first request, thread-safely.


Return the main_resource_dir.

  setenv (String, String) (environment_variable, value);

Set the value of the environment_variable, thread-safely.


Return the hostname of this machine. If the class variable is not set, it is set once from gethostname(2).


Return the directory in which all TOM stuff has been installed. This returns the value of TOM_PREFIX in the Constants class.

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


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.


Increase the quit_inhibit flag. Any increase should be accompanied later on by the corresponding decrease.

  quit_inhibit > 0;

Decrease the quit_inhibit flag, raising a postponsed signal-int if indicated by quit_pending.


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.


Increase the panic_mode flag. Any increase should be accompanied later on by the corresponding decrease.

  panic_mode > 0;

Decrease the panic_mode flag, raising a signal-int if requested by quit_pending.


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.

    printStack OutputStream stream
  ignoreUntil: String ignore_until_symbol = "";

Print a stack trace to an OutputStream.

instance tom.Runtime

The Runtime instance is totally empty.