Next: , Up: Transferring Control between Nodes   [Contents][Index]


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, executes the node, and exits when node execution finishes. A just called node resets its current state to initial one. When processing instruction invocations for executed nodes, the event handlers of instruction meta-classes can call this function recursively, including multiple times for the same node.

Transferring control to the node begins with sending an event QSMM_EVT_NODE_ENTER to the event handler of instruction class set of that node with passing the parameter paramp to that event handler. 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 highest reserved node identifier is greater than 0, the function loads a default uniform probability profile into the node. While executing the node, the function sends events QSMM_EVT_ACTIVATE to the event handlers of instruction meta-classes to process the invocations of instructions the instruction emitting engine is selecting. On finishing node execution, before returning control to a caller, the function sends an event QSMM_EVT_NODE_LEAVE to the instruction class set with passing the parameter 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_UNTIMELY

The model instance does not exist.

QSMM_ERR_NOTFOUND

A node with identifier node does not exist.

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 this value.

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_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_sig_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_MPROF

No room in the pool of probabilities lists in normal form for a large actor representing the environment state identification engine or instruction emitting engine when loading a default uniform probability profile into the node. The fields profile_pool_env_sz and profile_pool_opt_sz of qsmm_desc_s structure specify the pool sizes when creating the multinode model.

QSMM_ERR_NOPROF

The function cannot generate a uniform probability profile for the node, because the action emission matrices of all nodes have the restriction to define only deterministic action choices (field is_determ_opt of qsmm_desc_s structure specifies this mode), but the instruction class set of that node contains multiple instruction classes. It is necessary to load a probability profile into the node explicitly.

QSMM_ERR_UNSUPPLA

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 the multinode model.

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 the 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.


Next: , Up: Transferring Control between Nodes   [Contents][Index]