QSMM supports deferred copying a probability profile from a source node to a destination node, where a copying operation itself only sets a correspondence between the two nodes: the source node becomes a probability profile source, and the destination node becomes a probability profile user. A node can be a probability profile source for multiple other nodes. Storage redirection functions described in Specifying Redirection Functions provide read-only access for the destination node to a probability profile held in the source node.
The deferred copying operation provides copy-on-write behavior for instances of qsmm_state_s and qsmm_cycle_s structures described in Structures for Accessing Storage.
The instances hold a probability profile along with statistics on the event history.
The first operation of writing statistics to such an instance for the destination node causes allocating the instance and copying there a piece of information on the probability profile from the source node.
You can change values of controlled probability variables for the destination node in the normal way.
An assembler program loaded into the source node provides information on how to update the state transition matrix and action emission matrix of the destination node when changing its values of controlled probability variables.
Updating the state transition matrix and action emission matrix causes allocating instances of qsmm_state_s and qsmm_cycle_s structures for the destination node if they do not yet exist.
The following information held in a source node becomes automatically available for a destination node:
qsmm_get_node_var_prob_out, qsmm_get_node_array_prob_out, qsmm_get_node_var_prob_cycle, qsmm_get_node_array_prob_cycle, qsmm_get_node_var_prob_mat, qsmm_get_node_array_prob_mat, and qsmm_enum_var_prob_out called for the destination node use this information.
qsmm_get_node_state_name and qsmm_get_node_state_by_name called for the destination node retrieve this information.
The function qsmm_node_disasm called for the destination node can use this information.
The functions qsmm_mat_goto_dump_v2 and qsmm_mat_action_dump_v2 called for the destination node use this information.
qsmm_node_disasm called to disassemble the destination node automatically applies the template.
You cannot perform the following operations on a node acting as a probability profile source for other nodes:
qsmm_node_asm;
qsmm_node_profile_clone;
qsmm_set_node_profile_source;
qsmm_node_unload;
qsmm_node_destroy;
qsmm_node_var_realize.
You cannot perform the following operations on a node acting as a user of a probability profile provided by another node:
qsmm_node_profile_clone.
When disassembling a node acting as a probability profile user or dumping its state transition matrix or action emission matrix, keep in mind that a set of probabilities of QSMM_PROB_PROFILE type can be incomplete for the node, as some instances of qsmm_state_s structure from a source node might not yet be available for the destination node.
Therefore, avoid calculating probabilities of QSMM_PROB_PROFILE type for a node acting as a probability profile user.
Using the deferred copying mechanism for some or all nodes of a multinode model slows down all access operations to storage used by the multinode model approximately twice (even for other nodes).
Use the following function to set a correspondence between two nodes of a multinode model where one node becomes a probability profile source and the other node becomes a probability profile user.
int qsmm_set_node_profile_source (qsmm_t model, qsmm_sig_t node_from, qsmm_sig_t node_to, int rez1) ¶This function sets a node of a multinode model as the source of a probability profile and sets another node as a user of the probability profile. The argument node_from specifies the identifier of the source (former) node, and the argument node_to specifies the identifier of the destination (latter) node. The argument rez1 is for future use and must be equal to 0.
The function clears event history statistics collected for the destination node.
If it has a probability profile loaded, the function unloads the profile along with dependent information.
To clear event history statistics and unload the profile, this function calls the function qsmm_node_unload described in Unloading the Probability Profile.
If the source node has uncommitted assignments to controlled probability variables, qsmm_set_node_profile_source calls the function qsmm_node_var_realize to commit them.
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_INVALThe argument node_from is equal to the argument node_to.
QSMM_ERR_NOTFOUNDThe source or destination node does not exist.
QSMM_ERR_UNTIMELYA model instance does not exist.
QSMM_ERR_NOPROFThe source node does not have a probability profile specified.
QSMM_ERR_PROFSRCUThe source node is a user of a source probability profile provided by another node.
QSMM_ERR_PROFSRCPOne of the following conditions is true:
qsmm_set_node_profile_source called qsmm_node_var_realize to commit them, and the latter function has failed because the node is a probability profile source for other nodes.
This error can leave the probability profile of the destination node in inconsistent state. If after removing a reason of the error a repeated call to this function succeeds, the probability profile becomes consistent.
QSMM_ERR_NOEQCLASThe instruction class set of the source node and the instruction class set of the destination node are different.
QSMM_ERR_NOTSUPThe multinode model has positive length of look-ahead signal segment.
QSMM_ERR_PSUMGT1The source node had uncommitted assignments to controlled probability variables, so qsmm_set_node_profile_source called qsmm_node_var_realize to commit them, and the latter function has failed because the sum of probabilities of case instructions in a choice instruction block would exceed 1.
This error can leave the probability profile of the source node in inconsistent state.
If after removing a reason of the error a repeated call to qsmm_set_node_profile_source succeeds, the probability profile becomes consistent.
QSMM_ERR_STORAGEA Storage API function reported storage failure.
QSMM_ERR_STATSInconsistent statistics on an action choice state or cycle type detected.
QSMM_ERR_ILSEQUnable to convert a multibyte string to a wide string or vice versa according to a current locale.
QSMM_ERR_NOMEMThere was not enough memory to perform the operation.
Errors QSMM_ERR_STORAGE, QSMM_ERR_STATS, QSMM_ERR_ILSEQ, and QSMM_ERR_NOMEM can leave the probability profile of the source or destination node in inconsistent state.
If after removing a reason of an error a repeated call to this function succeeds, the probability profile becomes consistent.
The function qsmm_node_unload described in the next section can break off a correspondence between a node acting as a probability profile source and a node acting as a probability profile user.