Creating Nodes (QSMM Programmer Manual)

Next: Creating the Model Instance, Previous: Node Parameters, Up: Creating a Multinode Model [Contents][Index]

4.2.5 Creating Nodes ¶

Use the following function to create a node belonging to a particular node class represented by an instruction class set.

Function: int qsmm_node_create_v2 (qsmm_t model, const char *node_class_name, int rez1, qsmm_sig_t *node_p) ¶

This function creates a node of a multinode model. The node belongs to a node class represented by an instruction class set named node_class_name.

If node_p is NULL, or *node_p is QSMM_SIG_INVALID, the function finds the lowest unused identifier for a new node; if node_p is not NULL, the function returns that identifier in *node_p. If node_p is not NULL, and *node_p is not QSMM_SIG_INVALID, *node_p specifies an unused identifier for a node to create; in this case, *node_p remains unchanged on function completion. The argument rez1 is for future use and must be equal to 0.

The node takes initial values of basic parameters listed in Node Parameters. If the model instance exists, the node also takes initial values of extended parameters listed in that section.

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_INVAL: The argument node_p is not NULL, and *node_p is not equal to QSMM_SIG_INVALID but is greater than or equal to the maximum number of nodes in the model specified using the field nnode_max of qsmm_desc_s structure when creating the model.
QSMM_ERR_NOTFOUND: The instruction class set node_class_name does not exist.
QSMM_ERR_TYPE: An entity named node_class_name is not an instruction class set. The entity is an instruction meta-class.
QSMM_ERR_EXIST: The argument node_p is not NULL, *node_p is not equal to QSMM_SIG_INVALID, and a node with identifier *node_p already exists.
QSMM_ERR_MNODE: Creating a node would result in exceeding the maximum number of nodes in the model specified using the field nnode_max of qsmm_desc_s structure when creating the model.
QSMM_ERR_NOMEM: There was not enough memory to create a node.

Use the following macro to create a node from within the event handler function of an instruction class set where the name of that event handler function is the name of the instruction class set.

Macro: QSMM_NODE_CREATE (node) ¶

This macro expands to:

do {                                                       \
    qsmm_sig_t sig_node=(node);                            \
    qsmm_node_create_v2((qsmm),__FUNCTION__,0,&sig_node);  \
}                                                          \
while (0)

The macro is for creating a model node with identifier node from within the event handler function of an instruction class set representing the node class of the node. The name of that event handler function must be the same as the name of the instruction class set. The variable qsmm holding a model handle must be accessible in the event handler function. Normally, that variable is an event handler function argument.

The function qsmm_destroy destroys a multinode model and all its nodes. The following function destroys a specific node.

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

This function destroys a node with identifier node contained in a multinode model. The identifier becomes the unused one. The function destroys all parameters of the node listed in Node Parameters.

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_PROFSRCP: A node with identifier node is the source of a probability profile for other nodes. See Memory Efficient Cloning the Probability Profile, for more information on this mode.
QSMM_ERR_NOMEM: There was not enough memory to perform the operation. This error can leave the node in inconsistent state. If after removing a reason of this error a repeated call to this function succeeds, it completely destroys the node.

Use the following function to get the number of nodes in a model.

Function: qsmm_sig_t qsmm_get_nnode (qsmm_t model) ¶: This function returns the number of existing nodes in a multinode model.

Use the function described below to get the name of node class of a node. You can also use this function to test whether a node with a particular identifier exists.

Function: const char * qsmm_get_node_class_name (qsmm_t model, qsmm_sig_t node) ¶: This function returns the name of instruction class set of a node with identifier node contained in a multinode model. If the node does not exist, the function returns NULL.

If a node does not have an explicitly specified probability profile, the node uses a default uniform probability profile. In this case, a prerequisite for successful learning a state model by the node is that the default probability profile has a sufficient number of states. On the other hand, the more states the default probability profile has, the more instructions the node generally needs to execute to learn a state model.

The number of states of a default uniform probability profile for a just created node is equal to the maximum number of states specified for the instruction class set of the node. See Registering the Set, for the descriptions of qsmm_get_nstate_max_v2 and qsmm_set_nstate_max functions for retrieving and setting that maximum number of states.

After creating a node, you can use the function qsmm_set_node_nstate to change the number of states of a default probability profile for the node to a value less than maximum allowed one specified for the instruction class set if the environment state identification engine is a small actor, or the maximum number of nodes in the model is greater than 1.

If the environment state identification engine or instruction emitting engine is a large actor, the maximum number of nodes in the model is greater than 1, and the function qsmm_node_call_default already called the node, that function loaded a default uniform probability profile into the node. In this case, qsmm_set_node_nstate does not change the number of states of an already loaded default probability profile.

Use the following functions to retrieve or set the number of states for default uniform probability profile of a node.

Function: int qsmm_get_node_nstate_v2 (qsmm_t model, int rez1, unsigned int flags, qsmm_sig_t node, qsmm_sig_t *nstate_p) ¶

This function retrieves the number of states of a default probability profile for a node with identifier node contained in a multinode model. A returned value is either default number of states equal to the maximum number of states specified for the instruction class set of the node or the number of states set for the node by the function qsmm_set_node_nstate.

The argument rez1 is for future use and must be equal to 0.

On success, the function returns a non-negative value and sets *nstate_p if nstate_p is not NULL. If the node exists, the function sets *nstate_p to the number of states of the default probability profile. If the node does not exist, and flags do not contain bitmask QSMM_EXCEPT_NOTFOUND, the function sets *nstate_p to QSMM_SIG_INVALID.

If the node does not exist, and flags contain QSMM_EXCEPT_NOTFOUND, the function returns negative error code QSMM_ERR_NOTFOUND.

Function: int qsmm_set_node_nstate (qsmm_t model, qsmm_sig_t node, qsmm_sig_t nstate) ¶

This function sets to nstate the number of states of a default probability profile for a node with identifier node contained in a multinode model.

If the function qsmm_node_call_default already called the node and loaded into it an assembler program specifying a default probability profile, you need to call the function qsmm_node_unload to make it possible for qsmm_node_call_default to load into the node an assembler program specifying a default probability profile with a different number of states. See Unloading the Probability Profile, for more information about qsmm_node_unload.

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_INVAL: The argument nstate is less than 2 or greater than the maximum allowed number of states specified for the instruction class set of the node.
QSMM_ERR_NOTFOUND: A node with identifier node does not exist.
QSMM_ERR_NOTSUP: The environment state identification 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 1. Use the function qsmm_set_nstate_max to set the number of states of the node before creating it.