# RT0

Proxy module for the run-time system. This module is used to pull in the executable code of the run-time system, and to mark the place of the run-time system's header files. This module's directory is added to the include path of the C compiler, so that ``__oo2c.h`', ``__typemap.h`', and so on, are picked up from here.

The compiler implicitly adds an import for this module to every module. A program may import this module directly, for example to gain access to meta data embedded by the compiler into a module's object file. Please note that this module should be considered a part of the compiler, not of the standard library. As such, it may differ across different compiler implementations, and for a given compiler its interface might change without prior notice.

Note: The math library ``libm`' is always linked in for the sake of the predefined function ENTIER.

Class List
Module |
Object |
Struct |

Class Summary: Module [Detail]

      +--RT0.Module

Field Summary
name-: Name Name of the module.
openCount-: LONGINT Number of times this module's open() function has been called from client modules.
typeDescriptors-: POINTER TO ARRAY OF Struct All type descriptors of this module that correspond to named types defined on the top level.
Constructor Summary
ThisModule(ARRAY OF CHAR): Module Returns the module descriptor for the module name.

Class Summary: Object [Detail]

      +--RT0.Object

Method Summary
Finalize() This procedure is called by the run-time system immediately before an object is collected by the garbage collector.

Class Summary: Struct [Detail]

      +--RT0.Struct

Field Summary
baseTypes-: POINTER TO ARRAY OF Struct Array element type, pointer base type, or list of record base types.
flags-: SET Holds attributes that control the way the run-time deals with values of this type (eg.
form-: SHORTINT Identifies which kind of type constructor variant is used.
len-: LONGINT Holds the length of an array, the number of open dimensions of an open array, or the extension level of a record.
module-: Module The module that defines this type descriptor.
name-: Name Type name.
size-: LONGINT Size of the data type in bytes.
tbProcs-: POINTER TO ARRAY OF PTR Table of type-bound procedures of a record type.
typeArgs-: POINTER TO ARRAY OF Struct For a qualified type strQualType, this array holds the base type followed by the type arguments applied to the base type, followed by NIL.
Constructor Summary
ThisType(Module, ARRAY OF CHAR): Struct Returns the type descriptor for the type name of module mid.
TypeOf(PTR): Struct Returns the type of the record pointer ptr.

Type Summary
CaseRange = RECORD ... END
Name = POINTER TO ARRAY OF CHAR
charPtr1d = POINTER TO ARRAY OF CHAR
charPtr2d = POINTER TO ARRAY OF charPtr1d

Procedure Summary
CollectGarbage() Explicitly trigger a full, world-stop garbage collection.
ErrorAssertionFailed(Module, LONGINT, LONGINT)
ErrorDerefOfNil(Module, LONGINT)
ErrorFailedCase(Module, LONGINT, LONGINT)
ErrorFailedFunction(Module, LONGINT)
ErrorFailedTypeAssert(Module, LONGINT)
ErrorFailedTypeGuard(Module, LONGINT, Struct)
ErrorFailedWith(Module, LONGINT, Struct)
ErrorIndexOutOfRange(Module, LONGINT, LONGINT, LONGINT)
FreeBlock(PTR) Frees a block of memory allocated with NewBlock.
Halt(LONGINT)
NewBlock(LONGINT): PTR Allocates a memory block on the heap with a size of at least bytes bytes.
NewObject(Struct): PTR Allocates a new array or record variable on the heap, using the type descriptor td.
RegisterDisappearingLink(VAR PTR) Register the pointer ptr to be cleared when the object that it references is collected by the garbage collector.
RegisterModule(Module) Registers the module descriptor with the run-time system.
ScanCaseRanges(ARRAY OF CaseRange, LONGINT): PTR
TypeTest(Struct, Struct, Struct): BOOLEAN Return TRUE if the type tag tag belongs to an object that is an instance of the type td.
UnregisterDisappearingLink(VAR PTR) Undoes a registration of pointer ptr created by RegisterDisappearingLink.
UnregisterModule(Module) Unregisters the module descriptor from the run-time system.

Variable Summary
argc-: LONGINT
argv-: charPtr2d
boolean-: StructDesc
byte-: StructDesc
char-: StructDesc
integer-: StructDesc
longchar-: StructDesc
longint-: StructDesc
longreal-: StructDesc
poisonHeap: LONGINT If set to a non-negative value, then memory allocated through NewObject and NewBlock is filled with this byte value.
procedure-: StructDesc
ptr-: StructDesc
real-: StructDesc
set32-: StructDesc
shortint-: StructDesc
ucs4char-: StructDesc

Constant Summary
flagAtomic Indicates that this record type does not contain any references that need to be considered by the garbage collector.
flagFinalize Indicates that this record type has a Finalize procedure which should be called by the run-time system upon collection by the GC.
flagVTable Indicates that this record type has a vtable entry which must be initialised by NewObject.
strArray An array definition with a fixed length, as in ``ARRAY 123 OF CHAR`'.
strBoolean
strByte
strChar
strInteger
strLongchar
strLongint
strLongreal
strOpenArray An array definition with an unspecified length, as in ``ARRAY OF CHAR`'.
strPointer A pointer definition of the form ``POINTER TO T`'.
strProcedure A procedure type.
strPtr
strQualType A qualified type, specifying type arguments for a parametric type's parameter list.
strReal
strRecord A record, either in its C struct or union variant.
strSet32
strShortint
strTypeVar A type variable, for example used in a type test within in a type-bound procedure.
strUCS4Char

Class Detail: Module

Field Detail

### name

    FIELD name-: Name

> Name of the module.

### openCount

    FIELD openCount-: LONGINT

> Number of times this module's open() function has been called from client modules. At the same time, this is the number of client modules actively using this module.

### typeDescriptors

    FIELD typeDescriptors-: POINTER TO ARRAY OF Struct

> All type descriptors of this module that correspond to named types defined on the top level. Descriptors are listed in no particular order. The last element of the array has the value NIL.

Constructor Detail

### ThisModule

    PROCEDURE ThisModule(name: ARRAY OF CHAR): Module

> Returns the module descriptor for the module name. Result is NIL if no module of this name has been registered.

Class Detail: Object

Method Detail

### Finalize

    PROCEDURE (o: Object) Finalize()

> This procedure is called by the run-time system immediately before an object is collected by the garbage collector. This procedure may be used to reclaim any system resources (other than GC-managed memory) associated with this object (eg. OS handles). Any type that overrides this method is automatically registered for finalization by the run-time system.

> The Boehm GC finalizes objects in topological order. That is, if A points to B, and both are registered for finalization, it is guaranteed the A will be finalized first. This usually guarantees that finalization procedures see only unfinalized objects. For more details on finalization, see: http://www.hpl.hp.com/personal/Hans_Boehm/gc/finalization.html.

> Important: Program behaviour is undefined if this procedure raises an exception and passes it on to its caller. In this case, the caller is the garbage collector and it is not prepared to handle exceptions.

Class Detail: Struct

Field Detail

### baseTypes

    FIELD baseTypes-: POINTER TO ARRAY OF Struct

> Array element type, pointer base type, or list of record base types. For predefined scalar types this field is NIL.

### flags

    FIELD flags-: SET

> Holds attributes that control the way the run-time deals with values of this type (eg. see flagAtomic, flagVTable).

### form

    FIELD form-: SHORTINT

> Identifies which kind of type constructor variant is used.

### len

    FIELD len-: LONGINT

> Holds the length of an array, the number of open dimensions of an open array, or the extension level of a record.

### module

    FIELD module-: Module

> The module that defines this type descriptor. For predefined types, this is a reference to module ``RT0`'.

### name

    FIELD name-: Name

> Type name. NIL for anonymous types. For instances of strQualType, this is a fully expanded qualified type constructor of the form ``T(A1,A2,...)`'.

### size

    FIELD size-: LONGINT

> Size of the data type in bytes. For an open array type, which has no static size of its own, this field is size of the first element type that is not an open array.

### tbProcs

    FIELD tbProcs-: POINTER TO ARRAY OF PTR

> Table of type-bound procedures of a record type. This field is NIL for all other types.

### typeArgs

    FIELD typeArgs-: POINTER TO ARRAY OF Struct

> For a qualified type strQualType, this array holds the base type followed by the type arguments applied to the base type, followed by NIL. For the type arguments, the type descriptor of the record base type is stored, not that of the pointer type. For types other than strQualType, this field is NIL.

Constructor Detail

### ThisType

    PROCEDURE ThisType(mid: Module;
                       name: ARRAY OF CHAR): Struct

> Returns the type descriptor for the type name of module mid. If name defines a qualified type and there is no match in mid, then all modules of the program are searched. Result is NIL if there is no such type descriptor.

### TypeOf

    PROCEDURE TypeOf(ptr: PTR): Struct

> Returns the type of the record pointer ptr. The address ptr must be a previous result of NewObject. Result is undefined if ptr is not a reference to a record object.

Type Detail

### CaseRange

    TYPE CaseRange = RECORD
                         low-: LONGINT;
                         high-: LONGINT;
                         jmp-: PTR;
                     END

### Name

    TYPE Name = POINTER TO ARRAY OF CHAR

### charPtr1d

    TYPE charPtr1d = POINTER TO ARRAY OF CHAR

### charPtr2d

    TYPE charPtr2d = POINTER TO ARRAY OF charPtr1d

Procedure Detail

### CollectGarbage

    PROCEDURE CollectGarbage()

> Explicitly trigger a full, world-stop garbage collection.

### ErrorAssertionFailed

    PROCEDURE ErrorAssertionFailed(mid: Module;
                                   pos: LONGINT;
                                   code: LONGINT)

### ErrorDerefOfNil

    PROCEDURE ErrorDerefOfNil(mid: Module;
                              pos: LONGINT)

### ErrorFailedCase

    PROCEDURE ErrorFailedCase(mid: Module;
                              pos: LONGINT;
                              select: LONGINT)

### ErrorFailedFunction

    PROCEDURE ErrorFailedFunction(mid: Module;
                                  pos: LONGINT)

### ErrorFailedTypeAssert

    PROCEDURE ErrorFailedTypeAssert(mid: Module;
                                    pos: LONGINT)

### ErrorFailedTypeGuard

    PROCEDURE ErrorFailedTypeGuard(mid: Module;
                                   pos: LONGINT;
                                   typeTag: Struct)

### ErrorFailedWith

    PROCEDURE ErrorFailedWith(mid: Module;
                              pos: LONGINT;
                              typeTag: Struct)

### ErrorIndexOutOfRange

    PROCEDURE ErrorIndexOutOfRange(mid: Module;
                                   pos: LONGINT;
                                   index: LONGINT;
                                   length: LONGINT)

### FreeBlock

    PROCEDURE FreeBlock(ptr: PTR)

> Frees a block of memory allocated with NewBlock.

### Halt

    PROCEDURE Halt(code: LONGINT)

### NewBlock

    PROCEDURE NewBlock(bytes: LONGINT): PTR

> Allocates a memory block on the heap with a size of at least bytes bytes. Pointers in the allocated block are ignored during garbage collection. That is, the block must not contain any references to objects on the heap that are not kept live by other pointers.

### NewObject

    PROCEDURE NewObject(td: Struct): PTR

> Allocates a new array or record variable on the heap, using the type descriptor td. For an open array object, the lengths of the array's dimensions are passed as second, third, and so on, parameter. They must be of type LONGINT.

### RegisterDisappearingLink

    PROCEDURE RegisterDisappearingLink(VAR ptr: PTR)

> Register the pointer ptr to be cleared when the object that it references is collected by the garbage collector. Note: it is only safe to register pointers from heap objects, or global module variables. NEVER use this procedure for a pointer allocated on the stack (ie. a local variable or procedure parameter).

### RegisterModule

    PROCEDURE RegisterModule(mid: Module)

> Registers the module descriptor with the run-time system.

### ScanCaseRanges

    PROCEDURE ScanCaseRanges(table: ARRAY OF CaseRange;
                             value: LONGINT): PTR

### TypeTest

    PROCEDURE TypeTest(tag: Struct;
                       td: Struct;
                       receiverTag: Struct): BOOLEAN

> Return TRUE if the type tag tag belongs to an object that is an instance of the type td. For normal (that is, non-qualified) types, this is a constant type operation that is basically a pointer comparison. For qualified types, it compares the structure of both types. In this case, the function returns TRUE if the relevant base type of tag and td have the same base type, and if the corresponding type arguments are of the same type.

> Pre-condition: tag and td is the type descriptor of a ``RECORD`' type. If not NIL, receiverTag is the type descriptor of the record to which the procedure is bound.

### UnregisterDisappearingLink

    PROCEDURE UnregisterDisappearingLink(VAR ptr: PTR)

> Undoes a registration of pointer ptr created by RegisterDisappearingLink.

### UnregisterModule

    PROCEDURE UnregisterModule(mid: Module)

> Unregisters the module descriptor from the run-time system. Currently, this procedure is a noop.

Variable Detail

### argc

    VAR argc-: LONGINT

### argv

    VAR argv-: charPtr2d

### boolean

    VAR boolean-: StructDesc

### byte

    VAR byte-: StructDesc

### char

    VAR char-: StructDesc

### integer

    VAR integer-: StructDesc

### longchar

    VAR longchar-: StructDesc

### longint

    VAR longint-: StructDesc

### longreal

    VAR longreal-: StructDesc

### poisonHeap

    VAR poisonHeap: LONGINT

> If set to a non-negative value, then memory allocated through NewObject and NewBlock is filled with this byte value. Otherwise, the memory is left as provided by the used libc or libgc library. This is the default.

### procedure

    VAR procedure-: StructDesc

### ptr

    VAR ptr-: StructDesc

### real

    VAR real-: StructDesc

### set32

    VAR set32-: StructDesc

### shortint

    VAR shortint-: StructDesc

### ucs4char

    VAR ucs4char-: StructDesc

Constant Detail

### flagAtomic

    CONST flagAtomic

> Indicates that this record type does not contain any references that need to be considered by the garbage collector. It may be allocated as an atomic object.

### flagFinalize

    CONST flagFinalize

> Indicates that this record type has a Finalize procedure which should be called by the run-time system upon collection by the GC. This flag is set by the compiler for record types that override the method ObjectDesc.Finalize.

### flagVTable

    CONST flagVTable

> Indicates that this record type has a vtable entry which must be initialised by NewObject.

### strArray

    CONST strArray

> An array definition with a fixed length, as in ``ARRAY 123 OF CHAR`'.

### strBoolean

    CONST strBoolean

### strByte

    CONST strByte

### strChar

    CONST strChar

### strInteger

    CONST strInteger

### strLongchar

    CONST strLongchar

### strLongint

    CONST strLongint

### strLongreal

    CONST strLongreal

### strOpenArray

    CONST strOpenArray

> An array definition with an unspecified length, as in ``ARRAY OF CHAR`'.

### strPointer

    CONST strPointer

> A pointer definition of the form ``POINTER TO T`'.

### strProcedure

    CONST strProcedure

> A procedure type. Currently, all procedure types are mapped onto the single type descriptor procedure, even though they may differ in the number, type or mode of their parameters, or their result type.

### strPtr

    CONST strPtr

### strQualType

    CONST strQualType

> A qualified type, specifying type arguments for a parametric type's parameter list.

### strReal

    CONST strReal

### strRecord

    CONST strRecord

> A record, either in its C struct or union variant.

### strSet32

    CONST strSet32

### strShortint

    CONST strShortint

### strTypeVar

    CONST strTypeVar

> A type variable, for example used in a type test within in a type-bound procedure.

### strUCS4Char

    CONST strUCS4Char