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


4.17 Enumerating Entities

An instruction meta-class and an instruction class set are two special types of entities that can be stored within a multinode model. There are also several other types of entities that can be stored there. The notion of entity was introduced primarily to enable passing an entity type and an entity identifier to an error handler function as parameters of an error occurred. That notion has nothing to do with logical entities represented by nodes of the model.

Entity types are declared using the following enumeration.

Enumeration: qsmm_ent_e

This is an enumeration for categorizing entities stored within a multinode model. It contains the following elements.

QSMM_ENT_INVALID

Invalid entity type, which is currently used to indicate unknown entity type or a type of non-existent entity.

QSMM_ENT_INSTR_CLASS_SET

An instruction class set. Is identified by name. See Principle of Operation, for more information.

QSMM_ENT_INSTR_META_CLASS

An instruction meta-class. Is identified by name. See Principle of Operation, for more information.

QSMM_ENT_INSTR_CLASS

An instruction class. A human-readable identifier of the instruction class consists of an instruction meta-class name and, optionally, a whitespace character and a string representation of instruction parameters. See Principle of Operation, for more information.

QSMM_ENT_NODE

A node of multinode model. Is identified by a non-negative integer.

QSMM_ENT_VAR_PROB

A controlled or output probability variable. Is identified by name. See Using Probability Variables, for more information.

QSMM_ENT_ARRAY_PROB

[New in QSMM 1.16] An output probabilities array. Is identified by name. See Getting Output Probabilities Arrays, for more information.

QSMM_ENT_NODE_CLASS

A synonym for QSMM_ENT_INSTR_CLASS_SET.

Entities of types QSMM_ENT_INSTR_CLASS_SET and QSMM_ENT_INSTR_META_CLASS share the same namespace and must not have duplicate names. That was made because to each of those entities an event handler function with the same name usually corresponds, and function names must be unique.

The identifier of an entity can be stored in a union that contains fields for holding a string or numeric identifier.

Union: qsmm_ent_u

This union holds an identifier of an entity of one of the types defined by enumeration qsmm_ent_e. The union contains the following fields.

Field: char *name

A string identifier of the entity. Is applicable to entities of types QSMM_ENT_INSTR_CLASS_SET, QSMM_ENT_INSTR_META_CLASS, QSMM_ENT_INSTR_CLASS, QSMM_ENT_VAR_PROB, QSMM_ENT_ARRAY_PROB, and QSMM_ENT_NODE_CLASS.

Field: int id

A numeric identifier of the entity. Is applicable to entities of type QSMM_ENT_NODE.

To enumerate entities of given type stored within a multinode model, the following function can be used.

Function: int qsmm_enum_ent (qsmm_t model, enum qsmm_ent_e ent_type, qsmm_enum_ent_callback_func_t callback_func, void *paramp)

This function enumerates all entities of type ent_type stored in a multinode model specified by handle model. The process of enumeration is a repeated calling callback function callback_func, to which an entity type, an entity identifier, and user parameter paramp are passed. If the callback function returns a positive value, then the process of enumeration will be continued. If the callback function returns zero, then the process of enumeration will be terminated, and the function qsmm_enum_ent will report success. If the callback function returns a negative value, then the process of enumeration will be terminated, and the function qsmm_enum_ent will report failure.

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 ent_type is not QSMM_ENT_INSTR_META_CLASS, QSMM_ENT_INSTR_CLASS_SET, QSMM_ENT_NODE_CLASS, and QSMM_ENT_NODE.

QSMM_ERR_CALLBACK

The callback function did return an error.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

The type of a pointer to a callback function called for every enumerated entity is described below.

Data type: qsmm_enum_ent_callback_func_t

This is a type of callback function pointer with the following declaration:

typedef int (*qsmm_enum_ent_callback_func_t)(
    qsmm_t model,
    enum qsmm_ent_e ent_type,
    const union qsmm_ent_u *ent_p,
    void *paramp);

The callback function is called for every enumerated entity of a multinode model specified by handle model. The type of an entity is passed via argument ent_type, and an identifier of the entity is passed via argument ent_p. A user parameter is passed via argument paramp.

The callback function may return a positive value if the process of enumeration should be continued, zero if the process of enumeration should be terminated, or a negative value on error.

To get an entity type by an entity name, the following function can be used.

Function: enum qsmm_ent_e qsmm_get_ent_type_by_name (qsmm_t model, const char *ent_name)

This function returns the type of an entity named ent_name stored in a multinode model specified by handle model. The function only supports entities of types QSMM_ENT_INSTR_CLASS_SET and QSMM_ENT_INSTR_META_CLASS. If the entity does not exist or has another type, then the value QSMM_ENT_INVALID will be returned.


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