Next: Setting Look-ahead Signals, Previous: Transferring Control between Nodes, Up: Executing a Multinode Model [Contents][Index]

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:

- Set an instruction outcome by the function
`qsmm_set_instr_outcome`

. This operation is mandatory in certain cases. - Increment the current values of time and spur by the functions
`qsmm_time_delta`

and`qsmm_spur_delta`

. See Incrementing Time and Spur. - Call nodes by the function
`qsmm_node_call_default`

. See Calling a Node. - Return control to a caller node by the function
`qsmm_return_to_caller_node`

. See Returning Control from a Node. - Terminate model execution by the function
`qsmm_set_continue`

or macro`QSMM_TERMINATE`

. See Terminating Model Execution. - Access user frames in the node call stack obtained by the function
`qsmm_get_stack_frame`

. See Working with the Node Call Stack. - Change look-ahead signals by the function
`qsmm_set_la_sig`

. See Setting Look-ahead Signals. - 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.