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


4.19 Error Handling for a Multinode Model

A multinode model can have an error handler assigned to it. An error handler is a function, which is called in case of error raised by any QSMM API function that takes an argument of type qsmm_t and can return an error code. The default error handler function of multinode model prints information on an error occurred to stderr and calls exit(2). If there is no error handler function assigned to the model or an error handler function assigned to the model does not terminate program execution and returns, then an API function, where the error has occurred, will return corresponding error code.

To get or set an error handler for a multinode model, the following functions can be used.

Function: void qsmm_get_err_handler (qsmm_t model, qsmm_err_handler_func_t *func_p, void **param_pp)

This function retrieves information on the error handler assigned to a multinode model specified by handle model. If func_p is not NULL, then *func_p will be set to the pointer to an error handler function assigned to the model or to NULL if there is no such function assigned to the model. If param_pp is not NULL, then *param_pp will be set 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 specified by handle model. Argument func specifies an error handler function. Argument paramp specifies the user parameter of that function. If func is NULL, then no error handler will be used for the model.

An error handler function may receive extended information for some types of errors occurred.

Data type: qsmm_err_handler_func_t

This is the type of a pointer to an error handler function. To this type the following declaration corresponds:

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

The handle of a multinode model, to which an error pertains to, is passed via argument model. Information on the error is passed via argument except_p. A user parameter, specified when setting the error handler function for the model, is passed via argument paramp.

Below is a description of a structure that contains information on an error occurred.

Structure: qsmm_except_s

This structure is used to convey to the error handler function of multinode model information about an error occurred. The structure contains the following fields.

Field: const char * func_name

The name of a function within the QSMM library that has raised the error.

Field: int code

An error code that will be returned by the QSMM API function after return from the error handler function.

Field: union qsmm_except_u ee

Extended information on the error occurred. A list of error codes, for which this field always contains the extended information, is given in the description of union qsmm_except_u.

A union that contains extended error information, which depends on the error code, is described below.

Union: qsmm_except_u

This union contains fields that correspond to error codes for which extended error information is provided.

Field: char * noic

Extended information for error code QSMM_ERR_NOIC. A description of the error code is “instruction class set does not contain instruction classes.” This field contains the name of an instruction class set that does not contain instruction classes.

Field: int callback

Extended information for error code QSMM_ERR_CALLBACK. A description of the error code is “callback function returned an error.” This field contains an error code returned by the callback function.

Field: int noprof

Extended information for error code QSMM_ERR_NOPROF. A description of the error code is “node has no probability profile specified.” This field contains the identifier of a node that has no probability profile specified.

Field: int violnode

Extended information for error code QSMM_ERR_VIOLNODE. A description of the error code is “the change violates parameters of an already created node.” This field contains the index of a node, which parameters are violated.

Field: int mprof

Extended information for error code QSMM_ERR_MPROF. A description of the error code is “no room in the pool of probabilities lists in normal form.” This field contains the maximum possible number of probabilities lists in normal form that can be stored in the pool.

Field: int mnode

Extended information for error code QSMM_ERR_MNODE. A description of the error code is “too many nodes.” This field contains the maximum allowed number of nodes in the model.

Field: qsmm_msglist_t prg

Extended information for error code QSMM_ERR_PRG. A description of the error code is “invalid program.” This field contains a message list that hands over information on errors in the program.

Field: qsmm_storage_t storage

Extended information for error code QSMM_ERR_STORAGE. A description of the error code is “storage failure.” This field contains a reference to existing storage the failure pertains to.

Field: struct qsmm_except_notfound_s notfound

Extended information for error code QSMM_ERR_NOTFOUND. A description of the error code is “entity not found.”

Field: struct qsmm_except_type_s type

Extended information for error code QSMM_ERR_TYPE. A description of the error code is “invalid entity type.”

Field: struct qsmm_except_exist_s exist

Extended information for error code QSMM_ERR_EXIST. A description of the error code is “entity already exists.”

Field: struct qsmm_except_outcome_s outcome

Extended information for error code QSMM_ERR_OUTCOME. A description of the error code is “invalid instruction outcome.”

Field: struct qsmm_except_evthndlr_s evthndlr

Extended information for error code QSMM_ERR_EVTHNDLR. A description of the error code is “event handler function returned an error.”

Field: struct qsmm_except_nostate_s nostate

Extended information for error code QSMM_ERR_NOSTATE. A description of the error code is “not enough node states to hold the probability profile.”

Field: struct qsmm_except_nosamenc_s nosamenc

Extended information for error code QSMM_ERR_NOSAMENC. A description of the error code is “node classes are not the same.”

Field: struct qsmm_except_profsrcp_s profsrcp

Extended information for error code QSMM_ERR_PROFSRCP. A description of the error code is “node is the source of probability profile for other nodes.”

Field: struct qsmm_except_profsrcu_s profsrcu

Extended information for error code QSMM_ERR_PROFSRCU. A description of the 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. A description of the error code is “the sum of probabilities will exceed 1.”

There exists an API function that dumps the contents of structure qsmm_except_s to a stream in a human-readable form. This function is described below.

Function: void qsmm_except_dump (qsmm_t model, int indent, const struct qsmm_except_s *except_p, FILE *filep)

This function dumps error information contained in *except_p to stream filep in a human-readable form. To dump parameters of a node associated with the error (if such node exists), the function uses the value of argument model that must be the handle of a multinode model to which the error pertains to. Argument indent, which must be non-negative, specifies left indent, i.e. the number of spaces to print at the beginning of each line of output.

In the rest of this section, there are described structures that are the fields of union qsmm_except_u. In some of those structures, fields of types enum qsmm_ent_e and union qsmm_ent_u are used. See Enumerating Entities, for a description of these types.

Structure: qsmm_except_notfound_s

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

Field: enum qsmm_ent_e type

The type of an entity that was not found.

Field: union qsmm_ent_u ent

The name or the identifier of an entity that was not found.

Structure: qsmm_except_type_s

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

Field: enum qsmm_ent_e type

An invalid type of entity.

Field: enum qsmm_ent_e type_required

The required type for the entity.

Field: union qsmm_ent_u ent

The name or the identifier of an entity that has an invalid type.

Structure: qsmm_except_exist_s

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

Field: enum qsmm_ent_e type

The type of an entity that cannot be created, because an entity with the same name or identifier already exists.

Field: union qsmm_ent_u ent

The name or the identifier of an entity that cannot be created.

Structure: qsmm_except_outcome_s

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

Field: char * instr_meta_class_name

The name of meta-class of an instruction that has an invalid outcome.

Field: char * instr_param_str_p

The text representation of parameters of an instruction that has an invalid outcome or 0 if the instruction has no parameters.

Field: int node

The identifier of a node that has invoked the instruction.

Field: int outcome

An instruction outcome which is invalid.

Structure: qsmm_except_evthndlr_s

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

Field: int rc

A negative return value of the event handler function.

Field: int evt

The type of an event for which the event handler function was called (one of constants defined by QSMM_EVT_* macros).

Field: int node

The identifier of a node for which the event handler function was called. If there is no node associated with the event, then the identifier will be equal to -1.

Field: enum qsmm_ent_e type

The type of an entity, which events are handled by the event handler function.

Field: union qsmm_ent_u ent

The name of an entity, which events are handled by the event handler function.

Structure: qsmm_except_nostate_s

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

Field: int node

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

Field: int nstate_required

The minimum number of states the node must have to hold the probability profile.

Structure: qsmm_except_nosamenc_s

This structure provides extended information for error code QSMM_ERR_NOSAMENC. A description of the error code is “node classes are not the same.” The structure contains the following fields.

Field: char * node_class_name_1

The name of the first node class (i.e. instruction class set).

Field: char * node_class_name_2

The name of the second node class (i.e. instruction class set).

Structure: qsmm_except_profsrcp_s

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

Field: int node_provider

The identifier of a node that acts as a source of probability profile for other nodes.

Field: int n_profile_user

The number of nodes, which are users of the probability profile.

Structure: qsmm_except_profsrcu_s

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

Field: int node_provider

The identifier of a node that acts as a source of probability profile.

Field: int node_user

The identifier of a node, which is a user of the probability profile.

Structure: qsmm_except_psumgt1_s

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

Field: char * var_name

The name of a controlled probability variable, after assignment to which the sum of probabilities of case instructions in a choice instruction block or the sum of elements of a probabilities list used by a casels instruction will exceed 1.

Field: int node

The identifier of a node that contains a state to which the choice instruction block or the casels instruction corresponds.

Field: int state

The index of a node state to which the choice instruction block or the casels instruction corresponds.


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