Next: Creating the Model Instance, Previous: Instruction Class Set Definition, Up: Multinode Model [Contents][Index]

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:

- 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. - 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.- The environment state identification engine is represented by a large actor.
This mode is specified using the field