Events

Home > Model Development Topics > Events

This topic describes events. This topic is under construction and consists mostly of stub subtopics.

Related topics

• Model Code
• Event Trace: Probe a model run at the micro level
• Time-like and Event-like Attributes: Definition of time-like and event-like attributes, and restrictions on use
• Censor Event Time: How to activate and use the censor_event_time optimization option
• Entity Function Hooks: Entity function hooks

Topic contents

under construction

• Introduction and concepts
• Event time function

Introduction and concepts

under construction

Declaration syntax

Event life-cycle.

Event implement function

under construction

Changes attributes when the event occurs.

Event time function

under construction

This subtopic contains the following sections:

• Return value
• Attributes affecting event time

[back to topic contents]

Return value

under construction

The return value of an event time function is the (conditional) time when the event will occur. It can be current time or future time. It can be infinity. If it is a time in the past of the entity a run-time error will occur.

The WAIT function. WAIT(0) means now. But other events may occur first, depending on event priority and event tie rules.

Calling a time function must not influence the state of the simulation, because the associated event has not occurred (yet). Model code which attempts to change an attribute during an event time calculation will cause a run-time error.

No side-effect means simulation framework can call freely.

Clock-like events and hazard-like events.

The event time is recalculated when specific attributes change.

An attempt to use a time-like attribute in an event time function causes a build-time error.

[back to event time function]
[back to topic contents]

Attributes affecting event time

When an attribute changes value, any event whose time depends on that attribute must have its occurrence time recalculated in order to remain valid.

To determine which attributes affect which events, the OpenM++ compiler scans the C++ model code in the body of event time functions for attribute names. The scan is not based on the logic of the code in the event time function, only on the presence of names of attributes. The names can be attributes of the entity or attributes of another entity referenced directly through a link.

Modgen specific: Modgen does not support event dependency on linked attributes and forbids links to attributes in event time functions.

Consider the following code fragment (adapted from the Alpha2 test model):

entity Person
{
    //EN Integer age
    int integer_age = self_scheduling_int(age);
};
entity Thing
{
    //EN Count of celebratory birthday twirls performed
    int twirls = { 0 };
    //EN Do a twirl for the Person who spawned this Thing
    event timeTwirlEvent, TwirlEvent;
};

link Thing.spawner Person.things[];

TIME Thing::timeTwirlEvent()
{
    TIME event_time = TIME_INFINITE;
    if (spawner && (twirls < spawner->integer_age)) {
        event_time = WAIT(0); // twirl now!
    }
    return event_time;
}

void Thing::TwirlEvent()
{
    twirls++;
}

The TwirlEvent causes a Thing entity to twirl once on each birthday of the Person which spawned it.

The associated time function timeTwirlEventuses three attributes:

• spawner, a link attribute of Thing which connects it to the Person entity which spawned it,
• twirls, an attribute of Thing which counts the number of times the Thing has twirled, and
• spawner->integer_age, a self-scheduling attribute of Person which increases by 1 on each birthday.

The OpenM++ compiler notes the use of these three attributes in the event time function and generates run-time code which calls timeTwirlEvent in a Thing entity if any of those three attributes changes value.

Specifically, when integer_age of a Person is incremented on a birthday, the event time of TwirlEvent of all Thing entities spawned by that Person are recalculated. The code in timeTwirlEvent causes the TwirlEvent to be scheduled immediately by returning WAIT(0). After TwirlEvent is implemented and the twirl performed, timeTwirlEvent is called to schedule the next occurrence and returns infinity.

The OpenM++ compiler creates an output file which lists all attribute event dependencies. It is named EventDependencies.csv and is located in the src output folder, which in Windows is MODEL/ompp/src and in Linux is MODEL/ompp-linux/src.

For the Alpha2 test model, EventDependencies.csv looks like this:

entity	event	attribute
Person	BlowHornEvent	blow_horns_now
Person	EyeColourChangeEvent	eye_colour_definitive
Person	FirstBirthdayEvent	over_1
Person	MoveEvent	city
Person	SpawnEvent	spawning_done
Person	StartPlayingEvent	happy
Thing	BeingGoodEvent	making_trouble
Thing	TwirlEvent	spawner
Thing	TwirlEvent	twirls
Thing	TwirlEvent	spawner->integer_age
Thing	TwirlSpecialEvent	my_person1
Thing	TwirlSpecialEvent	twirls_special
Thing	TwirlSpecialEvent	my_person1->integer_age
Toy	DiscardEvent	lifetime

[back to event time function]
[back to topic contents]

Event scheduling

under construction

Extract from OM_ROOT/include/omc/Event.h:

/**
* event comparison. This is a true observer function but is not declared as const due to issues
* with get_event_id().
*
* @param [in,out] rhs The right hand side.
*
* @return true if the right-hand side is less than the left-hand side (this object).
*/
bool operator< ( BaseEvent& rhs )
{
    // earlier event time wins
    if ( event_time < rhs.event_time ) return true;
    if ( event_time > rhs.event_time ) return false;

    // higher event priority wins
    int event_priority = get_event_priority();
    int rhs_event_priority = rhs.get_event_priority();
    if ( event_priority > rhs_event_priority ) return true;
    if ( event_priority < rhs_event_priority ) return false;

    // lower event_id wins (earlier in alphabetic order by event name)
    int event_id = get_event_id();
    int rhs_event_id = rhs.get_event_id();
    if ( event_id < rhs_event_id ) return true;
    if ( event_id > rhs_event_id ) return false;

    // lower entity_id wins (created earlier)
    int entity_id = get_entity_id();
    int rhs_entity_id = rhs.get_entity_id();
    if ( entity_id < rhs_entity_id ) return true;
    else return false;
}

Self-scheduling events

under construction

Each entity has a built-in event which maintains all self-scheduling attributes in the entity.

Hooking to a self-scheduling attribute.

Tied events

under construction

The flow of time

under construction

Event loops

under construction

[back to topic contents]