Entity Function Hooks - openmpp/openmpp.github.io GitHub Wiki

Home > Model Development Topics > Entity Function Hooks

This topic describes the hook statement in model source code. It is used to chain the execution of one entity function to another entity function.

• Model Code

• Introduction and Motivation
• Syntax and Use Syntax and example
• Disambiguating Hook Order When hooks collide

Content to follow.

Content sketch:

• Increase modularity
• Reduce model code 'busy work'

[back to topic contents]

A hook statement is specified within an entity declaration, and has the form

    hook downstream_function, upstream_function, order;

The integer argument order is optional and is implicitly 0 if not specified.

In the following example, the downstream function StartCity is called by the upstream function `Start'.

entity Person
{
    void StartCity();
    hook StartCity, Start;
};

If an upstream function F has been hooked to by one or more downstream functions, the model developer must insert a call to a function named hook_F in the definition of the upstream function F. In the following example, the model developer inserted a call to the function hook_Start in an appropriate place in the definition of the function Start. The body of the function hook_Start is generated by the OpenM++ compiler, and calls, in hook order, all functions hooked to the Start function.

void Person::Start()
{
    // Initialize all attributes.
    initialize_attributes();
...
    hook_Start();

    // Have the entity enter the simulation.
    enter_simulation();
}

The OpenM++ compiler will raise an error if the body of a function contains no invocation of the hook_F function if one or more downstream functions hook to it.

[back to topic contents]

For the model source code to be logically well-specified, the order of invocation of multiple hooks to the same function must be specified.

For example, if the TestEventMemory.mpp module contains

actor Person
{
    //EN Start city
    void StartCity();
    hook StartCity, Start;
};

and the TestFixed.mpp module contains

actor Person
{
    //EN Set dog ownership
    void StartDogOwnership();
    hook StartDogOwnership, Start;
};

The OpenM++ compiler will issue two warnings like

TestEventMemory.mpp(93): warning : one or more functions hooking to 'Start' are ordered ambiguously with respect to 'StartCity'.
TestFixed.mpp(48): warning : one or more functions hooking to 'Start' are ordered ambiguously with respect to 'StartDogOwnership'.

The warning is issued for each hook statement which has an order tied to another hook statement. In this example, the two hook statements did not specify hook order, so they both had implicit order 0, creating ambiguity. The module and line number of these warnings are the code locations of the hook statements responsible for the ambiguity. In an IDE, the warning can be clicked to navigate directly to the hook statements responsible for the ambiguity.

To resolve the ambiguity, supply an explicit order to the hook which does not conflict, for example

    hook StartCity, Start, 1;
    hook StartDogOwnership, Start, 2;

[back to topic contents]