4.2.3.2 Event Handling

The event handler function of an instruction class set can process events with types represented by the macros listed below. The argument qsmm_evt of that event handler function specifies an event type.

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.

This event can trigger the following operations:

1. Register 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. Set the maximum number of states of nodes belonging to a node class represented by the instruction class set by the function qsmm_set_nstate_max. See Setting the Number of States.
4. Create nodes belonging to the node class by the function qsmm_node_create_v2 or macro QSMM_NODE_CREATE and set the number of states of each created node to a required value by the function qsmm_set_node_nstate. See Creating Nodes.
5. 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.

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

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

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 an 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 the identifier of this node via the argument qsmm_node and a user parameter of qsmm_node_call_default via the argument qsmm_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 system frame and, if user frame size is positive, a user frame.

This event can trigger the initialization of this user frame and setting its fields according to the argument qsmm_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 the identifier of this node via the argument qsmm_node and a user parameter of qsmm_node_call_default via the argument qsmm_param_p. After sending this event to the event handler, qsmm_node_call_default destroys a current frame in the node call stack comprised of a system frame and, if user frame size is positive, a user frame.

This event can trigger setting a value addressed by qsmm_param_p according to the fields of this 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. Such 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 be different in special cases. Use the function qsmm_get_eh_instr_class_set_name to get the name of an instruction class set while processing an event by the event handler of this instruction class set.