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

DEFINITION MODULE Handlers;

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

    Module  Handlers     (Version 1.0)

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

    Purpose   Management of event handlers which can be added and
              removed to particular event classes (dynamic class) by
              any number of clients and within a multilevel programming
              environment.

    Remarks   Upon program termination handlers are automatically
              removed if the program level to which they belong
              is to be left.  Note that whole classes are also
              automatically removed as a whole when the program
              level on which they have been instantiated is about
              to be left.


    Programming

      o Design
        Andreas Fischlin          22/01/1997

      o Implementation
        Andreas Fischlin          22/01/1997


    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:  04/03/1997  AF

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


  IMPORT SYSTEM;

  TYPE
    Object = SYSTEM.ADDRESS;

    EventClass;
    EventHandler = PROC;
    ObjectEventHandler = PROCEDURE (Object);
    EvtAcceptTester = PROCEDURE (): BOOLEAN;

    DoForClassProc = PROCEDURE (EventClass,
                                CARDINAL (*level*));
    DoForHandlerProc = PROCEDURE (EventHandler, ObjectEventHandler,
                                  BOOLEAN (*hasObject*),
                                  INTEGER (*priority*),
                                  CARDINAL (*level*) );
  CONST
    topPriority = 0;
    lowestPriority = MAX(INTEGER);

  VAR
    HandlersDone: BOOLEAN;          (* read only *)
    undeclaredClass: EventClass;    (* read only *)

  PROCEDURE DeclareEventClass(VAR class: EventClass);
  PROCEDURE ClassExists(class: EventClass): BOOLEAN;
  PROCEDURE RemoveEventClass(VAR class: EventClass);

  PROCEDURE AddEventHandler      (class: EventClass; newHdl: EventHandler;
                                  priority: INTEGER);
  PROCEDURE AddObjectEventHandler(class: EventClass; newHdl: ObjectEventHandler;
                                  priority: INTEGER);
    (* highest priority is 0, priorities < 0 are ignored and treated as 0 *)

  PROCEDURE RemoveEventHandler(class: EventClass; oldHdl: EventHandler);
  PROCEDURE RemoveObjectEventHandler(class: EventClass; oldHdl: ObjectEventHandler);

  PROCEDURE ExecuteEventHandlers(class: EventClass; obj: Object;
                                 whileNotAccepted: EvtAcceptTester;
                                 minLevel, maxLevel: CARDINAL;
                                 topPrio, lowPrio: INTEGER);
    (*
      Main messages sending routine executing all handlers
      (methods) currently associated with the event class
      class.  As soon as a handler has definitely accepted an
      event, procedure whileNotAccepted should return FALSE, so
      that no more handlers are executed.  If an event should
      be passed on to all its handlers, simply return TRUE
      unconditionally (see also procedure NotifyAll).  Only
      handlers with a subprogram level (see DMSystem) in range
      [minLevel..maxLevel] and a priority in the range
      [topPrio..lowPrio] are actually executed.  All handlers
      falling within a valid range are executed strictly in
      sequence according to priority.  Consequently, depending
      on the level on which the handler has been added,
      (sub)program levels may change during execution of this
      routine.  Handlers with an identical priority are
      executed in reverse order of their declaration.
    *)

  PROCEDURE NotifyAll(): BOOLEAN;
    (*
       EvtAcceptTester provided for your convenience, returns
       TRUE always
     *)


  PROCEDURE DoForAllClasses(cp: DoForClassProc);
  PROCEDURE DoForAllHandlers(class: EventClass; hp: DoForHandlerProc);


END Handlers.