---

4.3.2.1 Calling a Node ¶

Use the following function to call a node.

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

This function transfers control to a node with identifier node in a multinode model, resets current node state, executes the node, and exits when node execution finishes. While processing instruction invocations, event handlers of instruction meta-classes can call this function recursively, including multiple times for the same node.

At the beginning of its execution, the function creates a model instance if it does not exist and checks the flag retrievable by the function qsmm_get_continue (see Terminating Model Execution). If that flag indicates terminating model execution, qsmm_node_call_default exits.

Transferring control to the node begins with sending an event QSMM_EVT_NODE_ENTER to the instruction class set of the node with passing a parameter paramp to the event handler. If after sending the event, the flag retrievable by qsmm_get_continue indicates terminating model execution, or the flag retrievable by the function qsmm_get_mehcall_return (see Returning Control from a Node) indicates terminating node execution, or the node no longer exists, qsmm_node_call_default exits.

If the node does not have a probability profile specified, the environment state identification engine or instruction emitting engine is a large actor, and the maximum number of nodes specified using the field nnode_max of qsmm_desc_s structure when creating the model is greater than 1, the function loads into the node an assembler program defining a default uniform probability profile with the number of states retrievable by the function qsmm_get_node_nstate_v2 (see Creating Nodes).

After possible loading a default uniform probability profile, the function qsmm_node_call_default saves the first four signals of a tuple encoding a current action choice state of the environment state identification engine. See Figure 4.2, for the structure of this tuple. The function restores the saved four signals in the tuple at the end of function execution.

The function then enters a loop where it identifies a current node state by the environment state identification engine, selects an instruction class by the instruction emitting engine, and invokes an individual instruction or instruction sequence. On invoking an individual instruction, the function sends an event QSMM_EVT_ACTIVATE to the instruction meta-class of the individual instruction class. On invoking an instruction sequence, the function sends events QSMM_EVT_ACTIVATE to instruction meta-classes of individual instruction classes comprising the sequence. The function exits the loop if the flag retrievable by qsmm_get_continue indicates terminating model execution, or the flag retrievable by qsmm_get_mehcall_return indicates terminating node execution, or the node no longer exists.

Note: on deterministic identification (selection) of a current node state or deterministic selection of an individual instruction or instruction sequence, qsmm_node_call_default updates the fields sig_cycle_next and tmd0 in the structure qsmm_state_s but does not call the functions qsmm_actor_reg_ngram_in, qsmm_actor_calc_action_prob, and qsmm_get_actor_sig_action for the environment state identification engine or instruction emitting engine leaving discrete time tracked by the engine unchanged.

Before returning control to a caller, if qsmm_node_call_default sent the event QSMM_EVT_NODE_ENTER to the instruction class set, qsmm_node_call_default sends an event QSMM_EVT_NODE_LEAVE to the instruction class set with passing paramp to the event handler.

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

QSMM_ERR_NOTFOUND

A node with identifier node does not exist.

QSMM_ERR_OUTCOME

While processing an instruction invocation, the event handler of an instruction meta-class set an invalid instruction outcome or did not set an instruction outcome when it was necessary to do so. This error leaves the multinode model in inconsistent state.

QSMM_ERR_STACKOVR

The number of frames in the node call stack would exceed a value specified in the field stack_sz_max of qsmm_desc_s structure when creating the multinode model. The function qsmm_get_stack_sz_max returns the value.

QSMM_ERR_NGRAM

The content of a signal array encoding a current action choice state of the environment state identification engine accessible by the function qsmm_get_actor_sig_ngram is invalid.

QSMM_ERR_NOCHOICE

All instruction classes have zero weights, or weights of output signals of the environment state identification engine or instruction emitting engine are unexpectedly zero, or the probability profile of the environment state identification engine or instruction emitting engine is inconsistent.

QSMM_ERR_NOIC

The instruction class set does not contain instruction classes.

QSMM_ERR_NOPROF

The function cannot generate a uniform probability profile for the node, because state transition matrices of all nodes have the restriction to define only deterministic state transitions (field engine_desc[QSMM_ENGINE_ENV].is_determ of qsmm_desc_s structure is non-zero), or the instruction class set contains multiple instruction classes on condition that action emission matrices of all nodes have the restriction to define only deterministic action emissions (field engine_desc[QSMM_ENGINE_IEE].is_determ of qsmm_desc_s is non-zero). It is necessary to load a probability profile into the node explicitly.

QSMM_ERR_NOTSUP

The function cannot load a default uniform probability profile into the node, because the multinode model has positive length of look-ahead signal segment. The field ngram_env_la_sz of qsmm_desc_s structure specifies this length when creating a multinode model.

QSMM_ERR_CALLBACK

A helper function for computing the relative probability of an output signal assigned to the environment state identification engine or instruction emitting engine reported an error by returning NaN. The function qsmm_actor_calc_action_prob calls the helper function. This error leaves the multinode model in inconsistent state.

QSMM_ERR_INFIN

The function qsmm_actor_reg_ngram_in or qsmm_get_actor_sig_action called for the environment state identification engine or instruction emitting engine reported QSMM_ERR_INFIN. This error leaves the multinode model in inconsistent state.

QSMM_ERR_UNTIMELY

A handler of QSMM_EVT_NODE_ENTER event sent to the instruction class set or a handler of QSMM_EVT_ACTIVATE event sent to the instruction meta-class destroyed the model instance.

QSMM_ERR_STORAGE

A Storage API function reported storage failure. This error can leave the multinode model in inconsistent state.

QSMM_ERR_STATS

Inconsistent statistics on an action choice state or cycle type detected. This error can leave the multinode model in inconsistent state.

QSMM_ERR_ILSEQ

Unable to convert a multibyte string to a wide string or vice versa according to a current locale. This error can leave the multinode model in inconsistent state.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation. This error can leave the multinode model in inconsistent state.

Use the following function to get the number of calls of a node since creating the model instance.

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

This function retrieves the number of calls to a node with identifier node in a multinode model by the function qsmm_node_call_default since creating the model instance. If the model instance does not exist, the retrieved number of calls is 0. If fq_p is not NULL, the function sets *fq_p to a retrieved number of calls.

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

Use the function described below to get the number of nested calls to a node. You can use this function to prevent recursive calling a node if the model does not support recursive node calls.

Function: int qsmm_get_node_recurs (qsmm_t model, qsmm_sig_t node) ¶

On success, this function returns a non-negative number of nested calls to a node with identifier node in a multinode model by the function qsmm_node_call_default. If the node does not exist, the function qsmm_get_node_recurs returns negative error code QSMM_ERR_NOTFOUND.