Oberon || Library || Module Index || Search Engine || Definition || Module


Ulm's Oberon Library:
UntaggedStorage


NAME

UntaggedStorage - interface for storage not affected by garbage collection

SYNOPSIS

TYPE Address = Types.UntracedAddress;
TYPE Size = Types.Size;
CONST Nil = SYSTEM.VAL(Address, NIL);
TYPE Status = POINTER TO StatusRec;
TYPE StatusRec =
   RECORD
      (Objects.ObjectRec)
      allocated: Size;
      consumed: Size;
      chunksize: Size;
   END;


TYPE NewProc = PROCEDURE (size: Size) : Address; TYPE DisposeProc = PROCEDURE (ptr: Address); TYPE UseProc = PROCEDURE (ptr: Address; size: Size); TYPE GetStatusProc = PROCEDURE (VAR status: Status); TYPE ChunkSizeProc = PROCEDURE (size: Size) : Size; TYPE Interface = RECORD new: NewProc; dispose: DisposeProc; use: UseProc; getStatus: GetStatusProc; chunkSize: ChunkSizeProc; END;

PROCEDURE New(size: Size) : Address; PROCEDURE Dispose(ptr: Address);

PROCEDURE Use(ptr: Address; size: Size);

PROCEDURE GetStatus(VAR status: Status); PROCEDURE ChunkSize(size: Size) : Size;

PROCEDURE Init(if: Interface);

DESCRIPTION

UntaggedStorage provides an interface for storage unaffected by a garbage collection. Objects allocated using UntaggedStorage remain fixed in the address space and do not belong to the memory regions controlled by Storage and the garbage collector. As a consequence, the garbage collector must not be aware of pointers pointing onto such objects. On the other side, that objects should not contain pointers originating from NEW or SYSTEM.NEW, because the garbage collector will not update them. In addition to that, objects created with UntaggedStorage have no type tag and should be considered just as an interval of bytes. The compiler options P and/or O have to be switched off for pointer types pointing to such objects. This makes it possible for the compiler not to trace these pointers in pointer lists and to reject type tests.

Init is to be called during startup by the module which is implementing this interface. All interface procedures have to follow the semantics described below.

New tries to allocate an interval with the length of size bytes. On success, a reference to the requested region is returned. Otherwise, Storage.GarbageCollection is called and New retries the allocation. Finally, Nil is returned when not enough memory is available.

Dispose releases a memory region which has been created earlier by New. The parameter ptr is expected to represent the start of the interval.

Use puts the interval [ptr, ptr+size) into the free list of New for further consumption. This interval must not be allocated earlier using New, NEW or SYSTEM.NEW, but it can be every piece of memory which the garbage collector is not aware of. This example reuses a global static array:

CONST size = 1024;
VAR globalArray: ARRAY size OF BYTE;
(* ... *)
UntaggedStorage.Use(SYSTEM.VAL(UntaggedStorage.Address,
                               SYSTEM.ADR(globalArray)),
                    SYSTEM.SIZE(globalArray));

GetStatus returns a pointer to a record which contains information about the current storage status. The chunksize component contains the size of new memory regions which will be requested from the operating system when more memory is needed. The value returned in allocated represents the total number of bytes which are currently under control of UntaggedStorage, while consumed contains the number of bytes which are currently in use (consumed<=allocated).

ChunkSize allows to change the current chunk size. The chunk size is the size of new memory chunks when the storage allocator requests more memory from the system. There may be several system-dependent requirements which the chunk size has to meet, such as concerning address space utilization or the system's page size: ChunkSize rounds size to the next higher possible value, if the given parameter can not be used as new chunk size (generally, it should be a good idea when size is a power of 2 and greater than the page size). As result, the computed value is returned. In case of size = 0, ChunkSize only returns the current chunk size and no change is made.
Especially, when allocating objects with sizes greater than the page size, changing the chunk size can reduce the amount of memory needed from the operating system and increase performance.

DIAGNOSTICS

Calls to all interface procedures before Init lead to immediate program termination via Process.Exit (exit code 255).

SEE ALSO

Process
process termination
Storage
storage allocating interface for the compiler
SysStorage
storage allocator with copying garbage collection.
oc
compiler options

AUTHOR

Hansjörg Nägele, University of Ulm
Edited by: naegele, last change: 1995/11/17, revision: 1.3, converted to HTML: 1997/04/28

Oberon || Library || Module Index || Search Engine || Definition || Module