4.3.3 Handling Instruction Invocation

During the execution of a multinode model, its nodes execute instructions. When a node has to invoke an instruction, the node triggers an event QSMM_EVT_ACTIVATE of the instruction meta-class of this instruction.

On triggering the event QSMM_EVT_ACTIVATE, the function qsmm_node_call_default passes the identifier of that node to the event handler of that instruction meta-class via the argument qsmm_node. The event handler can fetch the binary parameters of the instruction class of this instruction by calling the function qsmm_get_eh_instr_param. The function qsmm_get_eh_instr_class_set_name retrieves the name of an instruction class set containing the instruction class. To fetch from the current frame of node call stack (see Working with the Node Call Stack) index idx that uniquely identifies the instruction class in the instruction class set, use this call:

qsmm_get_stack_instr_class(qsmm,0,&idx);

While processing an event QSMM_EVT_ACTIVATE, the event handler of an instruction meta-class can make changes to an environment or:

1. Set an instruction outcome by the function qsmm_set_instr_outcome. This operation is mandatory in certain cases.
2. Increment the current values of time and spur by the functions qsmm_time_delta and qsmm_spur_delta. See Incrementing Time and Spur.
3. Call nodes by the function qsmm_node_call_default. See Calling a Node.
4. Return control to a caller node by the function qsmm_return_to_caller_node. See Returning Control from a Node.
5. Terminate model execution by the function qsmm_set_continue or macro QSMM_TERMINATE. See Terminating Model Execution.
6. Access user frames in the node call stack obtained by the function qsmm_get_stack_frame. See Working with the Node Call Stack.
7. Change look-ahead signals by the function qsmm_set_la_sig. See Setting Look-ahead Signals.
8. Change the weights of instruction classes by the functions qsmm_set_instr_class_weight, qsmm_set_instr_class_weight_by_name_f, and qsmm_set_instr_meta_class_weight. See Setting Instruction Classes Weights.

An instruction outcome affects the selection of next node state after an instruction invocation. Use the following functions to query or set an instruction outcome.

Function: void qsmm_get_instr_outcome (qsmm_t model, int *outcome_p)

This function retrieves an instruction outcome associated with a multinode model. If outcome_p is not NULL, the function sets *outcome_p to a retrieved outcome.

An instruction outcome associated with a multinode model is last instruction outcome set by the function qsmm_set_instr_outcome while processing an instruction invocation event. If there was no call to qsmm_set_instr_outcome, and the instruction class has a positive number of outcomes, instruction outcome returned is -1. If there was no call to qsmm_set_instr_outcome, and the instruction class has zero number of outcomes, instruction outcome returned is the outcome of previous instruction invoked by the node after transferring control to it or 0 if there was no such instruction.

Function: int qsmm_set_instr_outcome (qsmm_t model, int outcome)

This function sets to outcome the instruction outcome associated with a multinode model. The function performs only a preliminary check on the validity of that outcome. The function qsmm_node_call_default performs final checks after a return from the event handler of a corresponding instruction meta-class, and, if the outcome is invalid, that function reports QSMM_ERR_OUTCOME.

On success, the function returns a non-negative value. If outcome is less than -1, the function returns negative error code QSMM_ERR_INVAL.

The function qsmm_set_eh_noutcome specifies the number of instruction outcomes during instruction class initialization. The default number of instruction outcomes used in case of omitting a call to that function is equal to 1. The number of instruction outcomes equal to 0 has special meaning.

Before calling the event handler of an instruction meta-class to process an event QSMM_EVT_ACTIVATE, the function qsmm_node_call_default sets the instruction outcome associated with the multinode model to -1 if the instruction class has a positive number of outcomes. If the instruction class has zero number of outcomes, qsmm_node_call_default sets the instruction outcome associated with the multinode model to the outcome of previous instruction invoked by the node after transferring control to it or to 0 if there was no such instruction.

After calling the event handler of an instruction meta-class to process an event QSMM_EVT_ACTIVATE, if node execution continues, the instruction outcome associated with the multinode model is equal to -1, and the number of outcomes of an instruction class is equal to 1, qsmm_node_call_default uses outcome 0 to select the next node state. This behavior makes it possible to omit calls to the function qsmm_set_instr_outcome for instruction classes with only one possible instruction outcome.

If after calling the event handler node execution continues, the instruction outcome associated with the multinode model is equal to -1, and the number of outcomes of an invoked instruction class is not equal to 1, qsmm_node_call_default reports QSMM_ERR_OUTCOME. This check compels to set an instruction outcome by qsmm_set_instr_outcome if the number of outcomes of an invoked instruction class is greater than 1.

If the instruction class has zero number of outcomes, the event handler of a corresponding instruction meta-class can call the function qsmm_get_instr_outcome on processing an event QSMM_EVT_ACTIVATE to analyze the outcome of previous instruction invoked by the node after transferring control to it. The event handler can leave that outcome intact or change it to a non-negative value less than the maximum number among the numbers of outcomes of instruction classes in the instruction class set of that node.

The functions described below return the probability of last state transition for a currently executed node and the probability of last instruction emission in a current node state. The probabilities have the type QSMM_PROB_AGGR and are in cells of the state transition matrix and action emission matrix of this node. You can call these functions while processing an event QSMM_EVT_ACTIVATE by the event handler of an instruction meta-class, for example, to compute the time when an instruction has to take effect.

Function: double qsmm_get_prob_goto (qsmm_t model)

This function returns the probability of last state transition performed just before last instruction invocation by a node of a multinode model. That probability has the type QSMM_PROB_AGGR and is in a cell of state transition matrix of this node. If the nodes of this model did not yet invoke instructions, the function returns 0. A returned value is always in the range 0 to 1 inclusive.

Function: double qsmm_get_prob_action (qsmm_t model)

This function returns the probability of last instruction emission in the current state of a node of a multinode model just after performing last state transition. That probability has the type QSMM_PROB_AGGR and is in a cell of action emission matrix of this node. If the nodes of this model did not yet invoke instructions, the function returns 0. A returned value is always in the range 0 to 1 inclusive.