Next: , Previous: , Up: Instruction Class Set Definition   [Contents][Index]


4.4.2 Event Handling

The event handler function of an instruction class set can process the types of events, which are represented by macros listed below. The type of event is passed to the event handler function via the argument qsmm_evt.

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.

A block of code, which handles the event, typically performs a subset of the following operations:

See Creating Nodes, for a description of macro QSMM_NODE_CREATE and the function qsmm_set_node_nstate.

Macro: QSMM_EVT_ENT_DONE

Instruction class set uninitialization. This event is sent to all registered event handlers of instruction class sets by the function qsmm_destroy called to destroy the multinode model.

In a block of code, which handles the event, additional resources could be freed that were allocated when processing event QSMM_EVT_ENT_INIT.

Macro: QSMM_EVT_ENGINE_INIT

Initialization of the model instance. This event is sent to all registered event handlers of instruction class sets (in lexicographical order of names of instruction class sets) by the function qsmm_engine_create, called to create the model instance, at the end of execution of that function.

In a block of code, which handles the event, setting up probability profiles for nodes could be performed, initial assignments to user variables specific to the model instance could be made, and additional resources specific to the model instance could be allocated.

Macro: QSMM_EVT_ENGINE_DONE

Uninitialization of the model instance. This event is sent by the function qsmm_engine_destroy to all registered event handlers of instruction class sets at the beginning of execution of that function in order, which is reverse to order, in which event QSMM_EVT_ENGINE_INIT was sent. The function qsmm_engine_destroy can be called explicitly, but is also called automatically when recreating the model instance by the function qsmm_engine_create and when destroying the multinode model by the function qsmm_destroy.

In a block of code, which handles the event, additional resources could be freed that were allocated when processing event QSMM_EVT_ENGINE_INIT.

Macro: QSMM_EVT_NODE_ENTER

Transferring control to a node that belongs to a node class represented by the instruction class set. The function qsmm_node_call_default, which calls a node, sends this event. An identifier of the node is passed to the event handler function via the argument qsmm_node, and a user parameter specified when calling the node is passed via the argument qsmm_param_p. Before sending this event to the event handler function, a frame in the system stack and a frame in the user stack (if this stack is used) are created.

In a block of code, which handles the event, initialization of the user stack frame could be performed. Fields of the user stack frame could be set in accordance with a value of argument qsmm_param_p.

To conserve memory and speed up program operation when a model contains many nodes, some of which will turn to be never called at all, a probability profile can be loaded into a node while processing this event on the first call to the node.

Macro: QSMM_EVT_NODE_LEAVE

Returning control from a node that belongs to a node class represented by the instruction class set. The function qsmm_node_call_default, which calls a node, sends this event. An identifier of the node is passed to the event handler function via the argument qsmm_node, and a user parameter specified when calling the node is passed via the argument qsmm_param_p. The frame in the system stack and the frame in the user stack (if this stack is used) are destroyed after sending this event to the instruction class set.

In a block of code, which handles the event, uninitialization of the user stack frame could be performed. Before the uninitialization, a value addressed by the argument qsmm_param_p could be set in accordance with the contents of the user stack frame.

Upon successful completion, the event handler function must return a non-negative value. Specific non-negative value will have no effect on system operation. On error, the event handler function should return a negative value; this will cause a model error handler to be invoked if it is set.

The name of an instruction class set and the name of its event handler function can be not the same in special cases. In the general case, to get the name of an instruction class set while processing an event by the event handler function of the instruction class set, the function qsmm_get_eh_instr_class_set_name can be used. That function is described in detail in Instruction Meta-class Event Handling.


Next: , Previous: , Up: Instruction Class Set Definition   [Contents][Index]