---

4.2.3.2 Event Handling ¶

The event handler function of an instruction class set can process events with types represented by macros listed below. Event type is available in mehcall->evt, where mehcall is an argument of that event handler function.

Macro: QSMM_EVT_ENT_INIT ¶

Instruction class set initialization. The function qsmm_reg_instr_class_set called to register the instruction class set sends this event if the instruction class set has an event handler function.

This event can trigger the following operations:

1. Register individual instruction classes belonging to the instruction class set by the macros QSMM_REG_INSTR_CLASS and QSMM_REG_INSTR_CLASS_PARAM. See Registering Instruction Classes.
2. Register controlled probability variables by the macro QSMM_REG_VAR_PROB. See Controlled Variables.
3. Create nodes belonging to the node class by the function qsmm_node_create_v2 or macro QSMM_NODE_CREATE. See Creating Nodes.
4. Associate user parameters with created nodes by the function qsmm_set_node_ptr. See Associating Parameters with a Model.

This event can also trigger initial assignments to variables and allocating resources used by the instruction class set for all model runs.

It might be convenient to perform the above operations outside of event handler function after calling qsmm_reg_instr_class_set.

Macro: QSMM_EVT_ENT_DONE ¶

Instruction class set uninitialization. The function qsmm_destroy called to destroy the multinode model sends this event to all registered event handlers of instruction class sets.

This event can trigger deallocating resources allocated on preparing the multinode model or processing the event QSMM_EVT_ENT_INIT.

Macro: QSMM_EVT_ENGINE_INIT ¶

Model instance initialization. The function qsmm_engine_create called to create the model instance sends this event to all registered event handlers of instruction class sets at the end of execution of that function.

This event can trigger the following operations:

1. Set parameters of actors representing the environment state identification engine and instruction emitting engine. See Creating the Model Instance.
2. Load assembler programs into nodes by the function qsmm_node_asm. See Loading a Parsed Program into a Node.
3. Clone node probability profiles by the function qsmm_node_profile_clone. See Cloning the Probability Profile.
4. Clone node probability profiles in deferred mode by the function qsmm_set_node_profile_source. See Memory Efficient Cloning the Probability Profile.

This event can also trigger initial assignments to variables and allocating resources used by the instruction class set for a current model run.

It might be convenient to perform the above operations outside of event handler function after calling qsmm_engine_create.

Macro: QSMM_EVT_ENGINE_DONE ¶

Model instance uninitialization. The function qsmm_engine_destroy called to destroy the model instance sends this event to all registered event handlers of instruction class sets at the beginning of execution of that function in reverse order relative to the order of sending events QSMM_EVT_ENGINE_INIT. The function qsmm_engine_create calls qsmm_engine_destroy implicitly when recreating the model instance. The function qsmm_destroy calls qsmm_engine_destroy implicitly when destroying the multinode model.

This event can trigger accumulating statistics collected during a current model run and deallocating resources allocated on processing the event QSMM_EVT_ENGINE_INIT.

Macro: QSMM_EVT_NODE_ENTER ¶

Transferring control to a node belonging to a node class represented by the instruction class set. The function qsmm_node_call_default sends this event on calling a node. The event handler receives a node identifier via mehcall->node and the user parameter of qsmm_node_call_default via mehcall->param_p. Before sending this event to the event handler, qsmm_node_call_default creates a frame in the node call stack comprised of a user frame if its size is positive and a system frame.

This event can trigger the initialization of the user frame and setting its fields according to mehcall->param_p.

Macro: QSMM_EVT_NODE_LEAVE ¶

Returning control from a node belonging to a node class represented by the instruction class set. The function qsmm_node_call_default sends this event on finishing calling a node. The event handler receives a node identifier via mehcall->node and the user parameter of qsmm_node_call_default via mehcall->param_p. After sending this event to the event handler, qsmm_node_call_default discards a current frame in the node call stack comprised of a user frame if its size is positive and a system frame.

This event can trigger setting a value addressed by mehcall->param_p according to the fields of the user frame with its subsequent uninitialization.

On successful completion, the event handler function shall return a non-negative value. A specific non-negative value has no effect on model operation. On error, the event handler function shall return a negative value. This negative value causes the invocation of an error handler function with passing QSMM_ERR_EVTHNDLR to it if the model has an error handler set.

The name of an instruction class set and the name of its event handler function can differ. Use the function qsmm_get_mehcall_instr_class_set to get the name of an instruction class set while processing an event by the event handler of the instruction class set.