DEFINITION MODULE OSStorage;

(*
    Title: 	OS-Dependent Heap Storge Allocator
    LastEdit:	"Mon Apr  9 18:41:31 1984"
    Author: 	jd
		Cambridge University Computer Laboratory
    VAX/Unix version
*)

FROM SYSTEM IMPORT ADDRESS;
EXPORT QUALIFIED WORDALIGN, ADDRESSESPERUNIT, HEAPALLOCATE;

(* this module exports two constants which will vary between
   Modula-2 implementations, and one procedure which is the 
   implementation-dependent way of obtaining more heap
*)

CONST WORDALIGN = TRUE;
    (* If true, then this Modula-2 implementation requires that all
       objects allocated from the heap be word aligned, ie that all
       storage allocations should be multiples of TSIZE (WORD)
    *)

CONST ADDRESSESPERUNIT = 1;
    (* since the choice of TSIZE (WORD) and hence of storage units is
       arbitrary, it is not obvious how to do address arithmetic. This
       constant defines how many addresses reside in one storage unit.
       It can thus be used to calculate the address
       following a  block of storage of a given size. 
    *)
    
PROCEDURE HEAPALLOCATE (of: CARDINAL; VAR base: ADDRESS; 
    VAR size: CARDINAL): BOOLEAN;

    (* This procedure incorporates ALL operating system dependencies
       about heap storage allocation. On entry, "of" is the minimum size of
       the contiguous block of heap storage which is required. "base" is the
       current base address of the free storage remaining to the 
       program, and should be NIL on the first ever call of the procedure. On
       subsequent calls, it must be an address within the last block of
       storage returned by this procedure, and size must give the number of
       storage units to the end of that block; thus base and size define the
       number of storage units remaining free in the last allocated block. 
       Note that all sizes are in the storage units defined by TSIZE, 
       NOT in Modula-2 words, and that base addresses accepted by and returned
       by this procedure are the arithmetically least addresses in the free
       block.

       On successful return, base will contain the base address of a 
       contiguous block of free storage, and size (>= of) will contain its
       size in storage units. The implementation is free either to allocate a
       completely new block of storage, or to extend the block of storage
       passed to it. It is also encouraged to allocate more storage than has
       been requested in the interests of efficiency. The caller may make
       no assumptions about the contiguity of the blocks returned by
       successive calls.
    *)

END OSStorage.
