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


4.5 Creating Nodes

To create a node, which belongs to a particular node class represented by an instruction class set, the following function can be used.

Function: int qsmm_node_create (qsmm_t model, const char *instr_class_set_name, int node)

This function creates a node of a multinode model specified by handle model. The node will belong to a node class represented by instruction class set instr_class_set_name. If node is non-negative, then the node will have identifier node.

If node is equal to -1, then the function will try to find an unused identifier for the node. If the model instance does not exist, then an identifier found will be an unused identifier in the range 0 to a value returned by the function qsmm_get_nnode inclusive. If the model instance exists, then an identifier found will be an unused identifier in the range 0 to a value returned by the function qsmm_get_nnode exclusive.

On success, the function returns a non-negative identifier of created node. On failure, the function returns a negative error code. Currently, the following error codes can be returned.

QSMM_ERR_INVAL

The value of node is less than -1 or is greater than QSMM_SIG_MAX.

QSMM_ERR_NOTFOUND

Instruction class set instr_class_set_name does not exist.

QSMM_ERR_TYPE

An entity named instr_class_set_name is not an instruction class set. The entity is an instruction meta-class.

QSMM_ERR_EXIST

A node with identifier node already exists.

QSMM_ERR_VIOLAP

Creating a node with identifier node will violate parameters of already created model instance. To be able to create nodes with greater identifiers after creating the model instance, call the function qsmm_node_reserve before creating the model instance. That function is described further on in this section.

QSMM_ERR_MNODE

The value of node is equal to -1, the model instance exists, but there are no unused node identifiers.

QSMM_ERR_NOMEM

There was not enough memory to create a node.

To create a node from within an event handler function of an instruction class set, where the name of the function is the name of the instruction class set, the following macro can be used.

Macro: QSMM_NODE_CREATE (node)

This macro is expanded to:

qsmm_node_create((qsmm), __FUNCTION__, (node))

The macro is intended for creating a model node with identifier node from within an event handler function of an instruction class set that represents a node class to which the created node will belong. The name of the event handler function must coincide with the name of the instruction class set, and normally it does coincide. There must be the variable qsmm, which is a handle of the multinode model, defined in a function from which the macro is expanded. Normally, that variable is an argument of the event handler function.

The created nodes are destroyed upon destruction of the whole multinode model, which is performed by the function qsmm_destroy. Starting from QSMM version 1.15 there is supported dynamic node destruction using the following function.

Function: int qsmm_node_destroy (qsmm_t model, int node)

This function destroys a node with identifier node contained in a multinode model specified by handle model. That identifier becomes the unused one. All statistics that might have been collected for the node is cleared.

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_NOTFOUND

A node with identifier node does not exist.

QSMM_ERR_PROFSRCP

A node with identifier node is the source of probability profile for other nodes. See Memory Efficient Cloning the Probability Profile, for more information on this mode.

QSMM_ERR_STORAGE

Statistics storage failure. This could leave the model instance in indeterminate state. If the model instance is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds or raises QSMM_ERR_NOTFOUND, then the model instance state will become determinate.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation. This could leave the model instance in indeterminate state. If the model instance is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds or raises QSMM_ERR_NOTFOUND, then the model instance state will become determinate.

To get the name of the node class of a node, the function described below can be used. This function can also be used to test whether a node with given identifier exists.

Function: const char * qsmm_get_node_class_name (qsmm_t model, int node)

This function returns the name of an instruction class set that represents the node class of a node with identifier node contained in a multinode model specified by handle model. If the node does not exist, then the function will return NULL.

To reserve node identifiers to allow creating nodes with greater identifiers after making the model instance, a function described below can be used. Without reserving, after making the model instance, nodes can be created with identifiers not greater than the highest identifier of a node created before making the model instance. The default number of reserved nodes is 1.

Function: int qsmm_node_reserve (qsmm_t model, int node)

This function ensures that the internal array of nodes of multinode model is capable of holding nodes with identifiers up to node inclusively. If necessary, the array is reallocated. Increasing array length can be performed when the model instance is not yet created. The length of the array is used as a parameter for creating the environment state identification engine and the instruction emitting engine that correspond to the model instance.

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_INVAL

The value of node is negative or is greater than QSMM_SIG_MAX.

QSMM_ERR_UNTIMELY

The length of an internal array, which holds nodes, needs to be increased, but the model instance has already been created.

QSMM_ERR_NOMEM

There was not enough memory to perform reallocation of an internal array that holds nodes.

To get the length of the internal array, the following function can be used.

Function: int qsmm_get_nnode (qsmm_t model)

This function returns the length of the internal array that holds nodes of a multinode model specified by handle model. Not all elements of the array may really contain nodes, some of them can have NULL values. The length of the array can be increased by the functions qsmm_node_create and qsmm_node_reserve. A value returned by this function is always positive.

A newly created node will have the number of states equal to the maximum allowed number of states of nodes that belong to a node class represented by an instruction class set specified when creating the node. See Setting the Number of States, for a description of functions qsmm_get_nstate_max and qsmm_set_nstate_max using which that maximum allowed number of states can be retrieved or modified. When the environment state identification engine is represented by a small actor or the model contains multiple nodes, the number of states of the node can later be changed to other value.

To retrieve or set the number of states of a node, the following functions can be used.

Function: int qsmm_get_node_nstate (qsmm_t model, int node)

This function returns the number of states of a node with identifier node contained in a multinode model specified by handle model.

On success, a positive value is returned. If node does not exist, then negative error code QSMM_ERR_NOTFOUND will be returned.

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

This function sets the number of states of a node with identifier node contained in a multinode model specified by handle model. The number of states is set to nstate.

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_INVAL

The value of nstate is less than 2 or is greater than the maximum allowed number of states of nodes of a node class a node with identifier node belongs to.

QSMM_ERR_NOTFOUND

A node with identifier node does not exist.

QSMM_ERR_NOSTATE

A node with identifier node has a probability profile loaded, and nstate is less than the minimum number of states a node must have to hold the probability profile.

QSMM_ERR_PROFSRCU

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

QSMM_ERR_NOTSUP

The following conditions are true at once:

  1. The environment state identification engine is represented by a large actor. This mode is specified using the field is_large_env of structure qsmm_desc_s when creating the multinode model.
  2. The model contains a single node with identifier 0. The function qsmm_get_nnode will return 1.

Use the function qsmm_set_nstate_max to set the number of states of the node.


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