Next: , Previous: , 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 node identifier for the 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 of 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 the initial values of basic parameters listed in Node Parameters. If the model instance exists, the node also takes the 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 QSMM_SIG_MAX.

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_VIOLAP

The model instance exists, and the identifier of a created node would be greater than the highest reserved node identifier (see the function qsmm_node_reserve).

QSMM_ERR_UNTIMELY

The identifier of a created node would exceed QSMM_SIG_MAX.

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 this 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 this node. The name of that event handler function must be equal to the name of this instruction class set. The variable qsmm holding the handle of a multinode model 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 this 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 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_STORAGE

A failure of statistics storage of a large actor representing the environment state identification engine. 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.

QSMM_ERR_STATS

Inconsistent statistics on an action choice state or cycle type detected for a large actor representing the environment state identification engine. 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.

QSMM_ERR_ILSEQ

For a large actor representing the environment state identification engine, a statistics storage access function generated an error message but cannot convert it to a wide string according to a current locale, or a storage redirection function reported QSMM_ERR_ILSEQ. 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.

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

At present, QSMM has the following limitation: after creating the model instance, the function qsmm_node_create_v2 and macro QSMM_NODE_CREATE cannot create nodes with identifiers greater than the highest reserved node identifier known before creating the model instance. That highest reserved identifier is a maximum number among the highest identifier of a node created by qsmm_node_create_v2 or QSMM_NODE_CREATE (before creating the model instance) and the highest identifier reserved by the function described below. The default highest reserved identifier is 0.

Currently, the highest reserved node identifier also defines whether tuples encoding the action choice states of the environment state identification engine and instruction emitting engine contain a node identifier: if the highest reserved identifier is greater than 0, the tuples contain the node identifier, otherwise they do not contain the node identifier. If the highest reserved identifier is 0, the function qsmm_node_call_default never generates an assembler program to set a default uniform probability profile.

Function: int qsmm_node_reserve (qsmm_t model, int node)

This function ensures that after creating the instance of a multinode model the function qsmm_node_create_v2 and macro QSMM_NODE_CREATE are able to create nodes with identifiers up to node inclusively. The highest reserved node identifier is currently a parameter for creating the environment state identification engine and instruction emitting engine. If the model instance already exists, the function qsmm_node_reserve only checks that node does not exceed a known highest reserved identifier.

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 is negative or greater than QSMM_SIG_MAX.

QSMM_ERR_UNTIMELY

The model instance already exists, and node is greater than the current highest reserved identifier.

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

Function: qsmm_sig_t qsmm_get_nnode (qsmm_t model)

This function returns the number of nodes in a multinode model.

A newly created node has the number of states equal to the maximum allowed number of node states specified for the instruction class set of this node. See Setting the Number of States, for the descriptions of qsmm_get_nstate_max and qsmm_set_nstate_max functions for retrieving and setting that maximum allowed number of states. If a small actor represents the environment state identification engine, or the highest reserved node identifier is greater than 0, you can change the number of node states to a lesser value by the function qsmm_set_node_nstate. If a large actor represents the environment state identification engine or instruction emitting engine, the highest reserved node identifier is greater than 0, and the function qsmm_node_call_default already called the node, that function loaded a default uniform probability profile into the node, so qsmm_set_node_nstate cannot change the number of node states to a lesser value.

Use the following functions to retrieve or set the number of node states.

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 node with identifier node contained in a multinode model.

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 node states. 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 node with identifier node contained in a multinode model.

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

QSMM_ERR_NOTFOUND

A node with identifier node does not exist.

QSMM_ERR_NOSTATE

The node has a probability profile loaded, and nstate is less than the number of states occupied by the probability profile.

QSMM_ERR_PROFSRCU

The node is a user of a probability profile provided by another node. See Memory Efficient Cloning the Probability Profile, for more information on this mode.

QSMM_ERR_NOTSUP

A large actor represents the environment state identification engine, and the highest reserved node identifier is 0. Use the function qsmm_set_nstate_max to set the number of states of this node before creating it.


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