Previous: , Up: Listing a Multinode Model   [Contents][Index]


4.4.4 Enumerating Entities

Instruction meta-classes and instruction class sets are entities a multinode model normally contains. Local entity references of QSMM_LREF_INSTR_META_CLASS and QSMM_LREF_INSTR_CLASS_SET types identify those entities by names. They share the same name space and cannot be duplicate, because those entities have event handler functions with names equal to entity names by default, and function names must be unique in certain scopes.

Use the following function to enumerate instruction meta-classes, instruction class sets, or nodes in a multinode model.

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

This function enumerates all entities of ent_type type stored in a multinode model. The process of enumeration is repeated calling a callback function callback_func receiving the type of a local entity reference, a local entity identifier, and a user parameter paramp. If the callback function returns a positive value, the function qsmm_enum_ent continues the enumeration. If the callback function returns zero, qsmm_enum_ent terminates the enumeration and reports success. If the callback function returns a negative value, qsmm_enum_ent terminates the enumeration and reports failure.

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_INVAL

The argument ent_type is not QSMM_LREF_INSTR_META_CLASS, QSMM_LREF_INSTR_CLASS_SET, and QSMM_LREF_NODE.

QSMM_ERR_CALLBACK

The callback function reported 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 below.

Data type: qsmm_enum_ent_callback_func_t

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

typedef int
(*qsmm_enum_ent_callback_func_t)(
    qsmm_t model,
    enum qsmm_lref_e lref_type,
    const union qsmm_lref_u *lref_p,
    void *paramp
);

An enumeration function calls the callback function for every enumerated entity of a multinode model. The argument lref_type specifies the type of an enumerated entity as the type of a local entity reference. The argument lref_p specifies the identifier of this entity as a local entity identifier. The argument paramp is a user parameter passed to the enumeration function.

The callback function shall return a positive value to continue the process of enumeration, zero to terminate the process of enumeration, or a negative value on error.

The function qsmm_enum_var_prob uses a callback function of qsmm_enum_ent_callback_func_t type for enumerating the controlled probability variables of an instruction class set. The function qsmm_enum_var_prob_out uses this callback function for enumerating the output probability variables of a node.

Use the following function to query the type of an entity by its name.

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

This function returns the type of a local entity reference for an entity named ent_name stored in a multinode model. The function only supports local entity references of QSMM_LREF_INSTR_META_CLASS and QSMM_LREF_INSTR_CLASS_SET types. If the entity does not exist or is not an instruction meta-class and instruction class set, the function returns QSMM_LREF_INVALID.


Previous: , Up: Listing a Multinode Model   [Contents][Index]