Next: , Previous: , Up: Multinode Model   [Contents][Index]


4.8 Transferring Control Between Nodes

Currently, transferring control to a node can only be performed by calling the node. A result of transferring control to the node is node activation (if the node is not already active) and node execution. When the node returns control to the caller, and the node is not called recursively, the node becomes the inactive one. Initially, when all nodes are inactive, activation of one of them is performed by a system that has created the multinode model. If there exist active nodes, then one of them will possess control and can call another node by transferring control to it. When calling a node, current state of the called node is reset to the initial one.

To transfer control to a node, the following function can be used.

Function: int qsmm_node_call_default (qsmm_t model, int node, void *paramp)

This function transfers control to a node with identifier node contained in a multinode model specified by handle model, executes the node, and exits when the node returns control to the caller.

Transferring control to a node begins with sending event QSMM_EVT_NODE_ENTER to an instruction class set, which is a node class of the node, and passing parameter paramp to the event handler function. If the node does not have a probability profile specified, the environment state identification engine and/or the instruction emitting engine are represented by large actors, and the model contains multiple nodes, then a default uniform probability profile will be loaded into the node. During the execution of the node, events QSMM_EVT_ACTIVATE are sent to meta-classes of instruction classes, which identifiers were generated by the instruction emitting engine. At the end of execution of the node, before returning control to the caller, event QSMM_EVT_NODE_LEAVE is sent to the instruction class set with passing parameter paramp to the event handler function.

The function returns a non-negative value on success or a negative error code on failure. Currently, the following error codes can be returned.

QSMM_ERR_UNTIMELY

The model instance does not exist.

QSMM_ERR_NOTFOUND

A node with identifier node does not exist.

QSMM_ERR_NOCHOICE

There are no positive weights assigned to instruction classes of an instruction class set which is a node class of node. The weights can be specified using the functions qsmm_set_instr_class_weight, qsmm_set_instr_class_weight_by_name_f, and qsmm_set_instr_meta_class_weight. The error will leave the multinode model in indeterminate state.

QSMM_ERR_NOPROF

A default uniform probability profile cannot be generated and loaded into node, because action emission matrices of all nodes are restricted to defining deterministic choice of action for every node state (which is specified using the field is_determ_opt of structure qsmm_desc_s when creating the multinode model), but an instruction class set, which is a node class of the node, contains multiple instruction classes. It is necessary to load a probability profile into the node manually.

QSMM_ERR_MPROF

There is no room in the pool of probabilities lists in normal form of a large actor that represents the environment state identification engine or the instruction emitting engine when loading a default uniform probability profile into node. Sizes of the pools are specified in the fields profile_pool_env_sz and profile_pool_opt_sz of structure qsmm_desc_s when creating the multinode model.

QSMM_ERR_OUTCOME

During the invocation of an instruction, its outcome was not set when it ought to be set, or an invalid instruction outcome was set. This will leave the multinode model in indeterminate state.

QSMM_ERR_STACKOVR

The number of frames in the node call stack will exceed the maximum allowed value. That value is specified in the field stack_sz_max of structure qsmm_desc_s when creating the multinode model and is returned by the function qsmm_get_stack_sz_max.

QSMM_ERR_UNSUPPLA

A default uniform probability profile cannot be loaded into node because the multinode model has positive length of the look-ahead signal segment. That length is specified in the field ngram_env_la_sz of structure qsmm_desc_s when creating the multinode model.

QSMM_ERR_ILSEQ

A text representation of instruction class parameters cannot be converted to a multibyte string according to the current locale. Such conversion is needed when filling the structure qsmm_except_outcome_s that corresponds to error code QSMM_ERR_OUTCOME returned by this function. See Error Handling for a Multinode Model, for more information on that structure. The error will leave the multinode model in indeterminate state.

QSMM_ERR_STORAGE

An Actor API function did return error QSMM_ERR_STORAGE. This could leave the multinode model in indeterminate state.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation. This could leave the multinode model in indeterminate state.

To get the number of times a node was called since the model instance had been created, the following function can be used.

Function: int qsmm_get_node_fq (qsmm_t model, int node, long *fq_p)

This function sets *fq_p to the number of times a node with identifier node contained in a multinode model specified by handle model was called since the model instance had been created. If the model instance does not exist, then the function will set *fq_p to 0. If fq_p is NULL, then *fq_p will not be set.

On success, the function returns a non-negative value. If a node with identifier node does not exist, then the function will return negative error code QSMM_ERR_NOTFOUND.

To get the number of nested calls to a node, the function described below can be used. The function might be used, e.g. to prevent calling already active nodes if the system does not support recursive node calls.

Function: int qsmm_get_node_recurs (qsmm_t model, int node)

On successful completion, this function returns the non-negative number of times control has been transferred to a node with identifier node contained in a multinode model specified by handle model and is not yet returned. Value 0 means that the node is inactive. Values greater than 0 mean that the node is active. If the node does not exist, then the function will return negative error code QSMM_ERR_NOTFOUND.

When a multinode model contains at least one active node, we can say the model is being executed. After finishing the process of modeling, e.g. when all input data are processed, model execution should be terminated. That is, all active nodes should return control and become inactive ones (the node call stack should become empty).

There is a flag associated with a multinode model, which is when set to a non-zero value, indicates that the process of modeling should be continued, and when set to zero value, indicates that the process of modeling should be successfully terminated. When creating the model instance, the flag is initialized to a non-zero value. To query or set the value of the flag, the following functions can be used.

Function: int qsmm_get_continue (qsmm_t model)

This function returns the flag that specifies whether the process of execution of a multinode model specified by handle model should be continued or terminated. If the function returns a positive value, then the process of model execution should be continued. If the function returns zero, then the process of model execution should be terminated. If the model instance does not exist, then the function will return negative error code QSMM_ERR_UNTIMELY.

Function: int qsmm_set_continue (qsmm_t model, int flag)

This function sets the flag that specifies whether the process of execution of a multinode model specified by handle model should be continued or terminated. If flag is non-zero, then the process of model execution should be continued. If flag is zero, then the process of model execution should be terminated.

On success, the function returns a non-negative value. If the model instance does not exist, then the function will return negative error code QSMM_ERR_UNTIMELY.

The flag, when has zero value, should cause to return from all nested calls to the function qsmm_node_call_default. The flag is automatically checked at the beginning of execution of that function, and if it has zero value, the function exits immediately. The flag is also automatically checked after sending event QSMM_EVT_NODE_ENTER to the instruction class set and after every instruction invocation, and if the flag is zero, the function qsmm_node_call_default exits. The flag can be explicitly analyzed using the function qsmm_get_continue after a call to qsmm_node_call_default when processing event QSMM_EVT_ACTIVATE by the event handler function of instruction meta-class to perform immediate exit from the event handler function when model execution is terminated.

To set the flag to zero, the following macro can also be used.

Macro: QSMM_TERMINATE ()

This macro is expanded to:

qsmm_set_continue((qsmm), 0)

You can use this macro to terminate the execution of a multinode model from within an event handler function having its argument qsmm equal to the handle of the multinode model.

For example, this macro can be called in a block of code that handles the invocation of an instruction (i.e. where event QSMM_EVT_ACTIVATE is processed by the event handler function of an instruction meta-class) to terminate the execution of a multinode model when all its input data are fetched by the instruction.

To return just from the last call to qsmm_node_call_default, the following function can be used.

Function: void qsmm_return_to_caller_node (qsmm_t model)

This function sets the flag that causes the function qsmm_node_call_default to exit. That flag is associated with a multinode model specified by handle model. The flag is reset before triggering event QSMM_EVT_NODE_ENTER for the instruction class set to process the transfer of control to the node and before triggering event QSMM_EVT_ACTIVATE for an instruction meta-class to process the invocation of an instruction by the node. The flag is checked after processing event QSMM_EVT_NODE_ENTER by the event handler function of an instruction class set and after processing event QSMM_EVT_ACTIVATE by the event handler function of an instruction meta-class. If the function qsmm_return_to_caller_node is called during processing instruction invocation, then an instruction outcome that might be set will be ignored.


Next: , Previous: , Up: Multinode Model   [Contents][Index]