Error Handling for a Multinode Model (QSMM Programmer Manual)

4.5 Error Handling for a Multinode Model

A multinode model can have an error handler assigned to it. The error handler is a function called in the case of a failure in any QSMM API function that takes an argument of qsmm_t type and can return an error code of int type. The default error handler of a multinode model prints information on an occurred error to stderr and calls exit(2). The output consists of the name of that default error handler function followed by an indented description of an error as object content in JSON format. If a multinode model does not have an error handler assigned (including the default error handler), or an error handler assigned to the multinode model does not terminate program execution and returns, a failed API function returns a corresponding error code.

Use the following functions to query or set an error handler for a multinode model.

Function: void qsmm_get_err_handler (qsmm_t model, qsmm_err_handler_func_t *func_p, void **param_pp): This function retrieves information on an error handler assigned to a multinode model. If func_p is not NULL, the function sets *func_p to the pointer to the error handler function or to NULL if the model does not have the error handler function assigned. If param_pp is not NULL, the function sets *param_pp to the user parameter of that error handler function.

Function: void qsmm_set_err_handler (qsmm_t model, qsmm_err_handler_func_t func, void *paramp): This function assigns an error handler to a multinode model. The argument func specifies an error handler function. The argument paramp specifies the user parameter of this error handler function. If func is NULL, the model does not use an error handler.

An error handler function receives extended information on some types of errors. The header file err.h included in qsmm.h contains a declaration for the type of an error handler function. The Side API also uses this type for the error handler of an interaction side (see Error Handling for the Side API, for more information).

Data type: qsmm_err_handler_func_t

This is a type of an error handler function pointer with the following declaration:

typedef void
(*qsmm_err_handler_func_t)(
    void *rez1,
    struct qsmm_except_s *except_p,
    void *paramp
);

The argument except_p passes information on an occurred error. The argument paramp is a user parameter specified when setting the error handler function for a multinode model. You should not access the reserved argument rez1.

The description of a structure containing information on an occurred error is below. The header file err.h contains the declaration of this structure.

Structure: qsmm_except_s

This structure is for passing information about an occurred error to an error handler function. The structure contains the following fields.

Field: const char * func_name: The name of a QSMM library function where the error occurred. That name might be the name of an internal library function and not an API function.

Field: int code: An error code to return by a failed QSMM API function after returning from the error handler function.

Field: union qsmm_except_u ee: Extended information on the occurred error. A list of error codes with extended error information always provided in this field is in the description of qsmm_except_u union.

The description of a union containing extended error information depending on an error code is below. The header file err.h contains the declaration of this union.

Union: qsmm_except_u

This union contains fields corresponding to error codes that can have associated extended error information.

Field: char * noic: Extended information for error code QSMM_ERR_NOIC. The description of this error code is “instruction class set is empty.” This field contains the name of an instruction class set without instruction classes.

Field: int callback: Extended information for error code QSMM_ERR_CALLBACK. The description of this error code is “callback function reported an error.” This field contains an error code returned by a callback function.

Field: qsmm_sig_t noprof: Extended information for error code QSMM_ERR_NOPROF. The description of this error code is “node has no probability profile specified.” This field contains the identifier of a node without a probability profile specified.

Field: qsmm_sig_t violnode: Extended information for error code QSMM_ERR_VIOLNODE. The description of this error code is “change violates the parameters of an already created node.” This field contains the identifier of a node that prevents making a change because it would violate the parameters of this node.

Field: qsmm_msglist_t prg: Extended information for error code QSMM_ERR_PRG. The description of this error code is “invalid program.” This field contains a message list that hands over information on errors in an assembler program.

Field: qsmm_storage_t storage: Extended information for error code QSMM_ERR_STORAGE. The description of this error code is “storage failure.” This field refers to failed storage.

Field: size_t mprof: Extended information for error code QSMM_ERR_MPROF. The description of this error code is “too many probabilities lists in normal form.” This field contains the maximum number of elements in the pool of probabilities lists in normal form.

Field: struct qsmm_except_notfound_s notfound: Extended information for error code QSMM_ERR_NOTFOUND. The description of this error code is “entity not found.”

Field: struct qsmm_except_type_s type: Extended information for error code QSMM_ERR_TYPE. The description of this error code is “invalid entity type.”

Field: struct qsmm_except_exist_s exist: Extended information for error code QSMM_ERR_EXIST. The description of this error code is “entity already exists.”

Field: struct qsmm_except_outcome_s outcome: Extended information for error code QSMM_ERR_OUTCOME. The description of this error code is “invalid instruction outcome.”

Field: struct qsmm_except_evthndlr_s evthndlr: Extended information for error code QSMM_ERR_EVTHNDLR. The description of this error code is “event handler function reported an error.”

Field: struct qsmm_except_nostate_s nostate: Extended information for error code QSMM_ERR_NOSTATE. The description of this error code is “not enough node states to hold the probability profile.”

Field: struct qsmm_except_noeqclas_s noeqclas: Extended information for error code QSMM_ERR_NOEQCLAS. The description of this error code is “node classes are different.”

Field: struct qsmm_except_profsrcp_s profsrcp: Extended information for error code QSMM_ERR_PROFSRCP. The description of this error code is “node is a probability profile source for other nodes.”

Field: struct qsmm_except_profsrcu_s profsrcu: Extended information for error code QSMM_ERR_PROFSRCU. The description of this error code is “node is a user of a source probability profile provided by another node.”

Field: struct qsmm_except_psumgt1_s psumgt1: Extended information for error code QSMM_ERR_PSUMGT1. The description of this error code is “sum of probabilities would exceed 1.”

Use the following function to dump the content of qsmm_except_s structure to a stream in JSON format.

Function: void qsmm_except_dump (void *rez1, int indent, const struct qsmm_except_s *except_p, FILE *filep): This function dumps error information in *except_p to a stream filep in JSON format as object content. The argument indent must be non-negative. It specifies left indent—the number of spaces to print at the beginning of each line of output. You should pass 0 for the reserved argument rez1.

The rest of this section describes the structures that are the fields of qsmm_except_u union. The header file err.h contains the declarations of those structures. Some of them have fields of enum qsmm_lref_e, struct qsmm_gref_s, and struct qsmm_instr_class_s types. See Entity References, for the descriptions of these types.

Structure: qsmm_except_notfound_s

This structure provides extended information for error code QSMM_ERR_NOTFOUND. The description of this error code is “entity not found.” The structure contains the following field.

Field: struct qsmm_gref_s gref: A reference to a not found entity.

Structure: qsmm_except_type_s

This structure provides extended information for error code QSMM_ERR_TYPE. The description of this error code is “invalid entity type.” The structure contains the following fields.

Field: enum qsmm_lref_e type_required: A required type for the entity.

Field: struct qsmm_gref_s gref: A reference to the entity that has an invalid type.

Structure: qsmm_except_exist_s

This structure provides extended information for error code QSMM_ERR_EXIST. The description of this error code is “entity already exists.” The structure contains the following field.

Field: struct qsmm_gref_s gref: A reference to an already existing entity.

Structure: qsmm_except_outcome_s

This structure provides extended information for error code QSMM_ERR_OUTCOME. The description of this error code is “invalid instruction outcome.” The structure contains the following fields.

Field: qsmm_sig_t node: The identifier of a node invoked the assembler instruction.

Field: qsmm_sig_t outcome: An invalid instruction outcome.

Field: qsmm_sig_t noutcome: The number of outcomes of the assembler instruction.

Field: qsmm_t model: A multinode model containing a node invoked the assembler instruction.

Field: struct qsmm_instr_class_s instr_class: The descriptor of an instruction class for the assembler instruction.

Structure: qsmm_except_evthndlr_s

This structure provides extended information for error code QSMM_ERR_EVTHNDLR. The description of this error code is “event handler function reported an error.” The structure contains the following fields.

Field: int rc: A negative return value of the event handler function.

Field: int evt: An event type passed to the event handler function—one of constants defined by the QSMM_EVT_* macros.

Field: int node: The identifier of a node associated with the event. A negative value means no node association.

Field: struct qsmm_gref_s gref: A reference to an entity emitting events processed by the event handler function.

Structure: qsmm_except_nostate_s

This structure provides extended information for error code QSMM_ERR_NOSTATE. The description of this error code is “not enough node states to hold the probability profile.” The structure contains the following fields.

Field: qsmm_sig_t node: The identifier of a node that has or would have the number of states less than it is necessary to hold the probability profile.

Field: qsmm_sig_t nstate_required: The minimum number of states the node must have to hold the probability profile.

Structure: qsmm_except_noeqclas_s

This structure provides extended information for error code QSMM_ERR_NOEQCLAS. The description of this error code is “node classes are different.” The structure contains the following fields.

Field: char * node_class_name_1: The name of the first node class, that is, the first instruction class set.

Field: char * node_class_name_2: The name of the second node class, that is, the second instruction class set.

Field: qsmm_sig_t node1: The identifier of a node belonging to the first node class. If that identifier is QSMM_SIG_INVALID, this parameter is not applicable.

Field: qsmm_sig_t node2: The identifier of a node belonging to the second node class. If that identifier is QSMM_SIG_INVALID, this parameter is not applicable.

Field: qsmm_t model: A multinode model containing the node classes.

Structure: qsmm_except_profsrcp_s

This structure provides extended information for error code QSMM_ERR_PROFSRCP. The description of this error code is “node is a probability profile source for other nodes.” The structure contains the following fields.

Field: qsmm_sig_t node_provider: The identifier of a node acting as a probability profile source for other nodes.

Field: qsmm_sig_t nnode_user: The number of nodes acting as probability profile users.

Field: qsmm_t model: A multinode model containing the nodes.

Structure: qsmm_except_profsrcu_s

This structure provides extended information for error code QSMM_ERR_PROFSRCU. The description of this error code is “node is a user of a source probability profile provided by another node.” The structure contains the following fields.

Field: qsmm_sig_t node_provider: The identifier of a node acting as a probability profile source.

Field: qsmm_sig_t node_user: The identifier of a node acting as a probability profile user.

Field: qsmm_t model: A multinode model containing the nodes.

Structure: qsmm_except_psumgt1_s

This structure provides extended information for error code QSMM_ERR_PSUMGT1. The description of this error code is “sum of probabilities would exceed 1.” The structure contains the following fields.

Field: char * var_name: The name of a controlled probability variable with an assigned value. This assignment causes the sum of probabilities of case instructions in a choice instruction block to exceed 1.

Field: qsmm_sig_t node: The identifier of a node containing a state corresponding to a choice instruction block.

Field: qsmm_sig_t state: The index of a node state corresponding to a choice instruction block.

Field: qsmm_t model: A multinode model containing the node.