RAMSES	Systems Ecology
Start         Modules:   A-Z   Function   Layer        QuickRefs:   DM   AuxLib   AuxLibE   SciLib   EasyMW   MW   ISIS   RMSLib

DEFINITION MODULE DMHeapWatch;

  (*******************************************************************

    Module  DMHeapWatch     ('Dialog Machine' DM_V3.0)

      Copyright (c) 1990-2006 by Andreas Fischlin and ETH Zurich.

    Purpose   Watches allocation and deallocation of heap blocks
              during program execution.

    Remarks   If not all heap blocks are returned by the program
              at its end, this module makes it possible to display
              a warning message.

              This module functions as follows: DMStorage calls
              the procedure variables exported by this module on
              particular occasions (explained below).  By default,
              only empty procedures are assigned to these
              procedure variables, which may be overwritten by
              other methods.  E.g. RMSDebugHelp assigns typically
              a reporting routine, hence the user is always
              informed accordingly, e.g. if garbage collection was
              necessary.

              Needs module DMDebugHelp.

              This module belongs to the 'Dialog Machine'.


    Programming

      o Design
        Andreas Fischlin          02/02/1990

      o Implementation
        Andreas Fischlin          02/02/1990


    ETH Zurich
    Systems Ecology
    CHN E 35.1
    Universitaetstrasse 16
    8092 Zurich
    SWITZERLAND

    URLs:
        <mailto:RAMSES@env.ethz.ch>
        <http://www.sysecol.ethz.ch>
        <http://www.sysecol.ethz.ch/SimSoftware/RAMSES>


    Last revision of definition:  09/04/1997  AF

  *******************************************************************)


  FROM SYSTEM IMPORT ADDRESS;

  CONST
    maxBlocks = 15;

  TYPE
    AllocInfo   =   PROCEDURE ( ADDRESS, ADDRESS, LONGINT, INTEGER );
                             (* pBefore, pAfter,  size,    level  *)

    DeallocInfo =   PROCEDURE ( ADDRESS, ADDRESS, INTEGER );
                             (* pBefore, pAfter,  level  *)


  VAR
    ptrCount, handleCount, windowCount, TECount, controlCount,
    menuCount, dialogCount: INTEGER;
    (* count current allocations of objects of above types as
    supported by the "Dialog Machine" and/or the Macintosh toolbox.
    On proper use of these objects the counts should all be 0 at the
    end of a program, since all objects allocated during program
    execution are also deallocated *)

    blockSizes: ARRAY [0..maxBlocks] OF LONGINT;
      (* used to filter reporting of those heap blocks, which match
      exactly one of the sizes "listed" in this array (starting from
      lowest element, assign 0D for elements not used).  if a heap block
      of the given size is encountered in an allocation, a message will
      be displayed informing the user about the fact.  *)


    debugProc: PROCEDURE ( ARRAY OF CHAR , INTEGER, LONGINT);
                           (* callee       level    size *)
      (* debugProc is called in DMStorage.AllocateOnLevel if the size of
      the requested block matches exactly one of the elements from
      blockSizes (compare allocInfoProc) *)


    showLevels: PROCEDURE ( ARRAY OF CHAR , INTEGER, LONGINT);
                           (* callee        level    size *)
      (* called in two cases:

        1) During garbage collection, i.e. called for each heap block
           which the automatic deallocation mechanism of DMStorage had
           to discard.  This is true for every heap block the programmer
           does not explicitely discard at the end of the allocating
           program level.  Hence, if you wish to rely on the garbage
           collection mechanism offered by the "Dialog Machine",
           ignore this event and don't assign a reporting procedure to
           this routine.

        2) Each time a call to DMStorage.DeallocateOnLevel fails, e.g.
           because an attempt is made to deallocate a block in a level
           in which it does not exist, showLevels is also called. Similarily
           to condition above, if you wish to rely on the automatic
           garbage collection, there is little need to be informed on
           this event, since the DM's garbage collector will deallocate
           all blocks, irrespective of the level on which they have
           been allocated.  However note, in contrast to occasion 1,
           the size of the heap block is unknown, since not found,
           thus 0D is passed as actual argument.

        Note, DMStorage.Allocate is implemented as
        DMStorage.AllocateOnLevel(DMSystem.CurrentDMLevel())
      *)


    allocInfoProc  : AllocInfo;
      (* called in DMStorage.AllocateOnLevel at end, unconditionally
      (compare debugProc).  Note, DMStorage.Allocate is implemented as
      DMStorage.AllocateOnLevel(DMSystem.CurrentDMLevel()) *)


    deallocInfoProc: DeallocInfo;
      (* called in DMStorage.DeallocateOnLevel at end, unconditionally.
      (compare showLevels). Note, DMStorage.Deallocate is implemented as
      DMStorage.DeallocateOnLevel(DMSystem.CurrentDMLevel()) *)


    clearBlockAtAlloc: BOOLEAN;
      (* if TRUE DMStorage fills every heap block after successful
      allocation with 0 (NIL). Otherwise a full and proper initialization
      is left to the client *)


END DMHeapWatch.