Next: , Previous: , Up: Statistics Storage   [Contents][Index]


3.4 Enumerating States and Cycle Types

To enumerate action choice states, information on which is held in storage, the following function can be used.

Function: int qsmm_storage_enum_states (qsmm_storage_t storage, int ngram_prefix_sz, const qsmm_sig_t *sig_ngram_prefix_p, qsmm_enum_states_callback_func_t callback_func, void *paramp)

This function enumerates action choice states, information on which is held in storage. Only those action choice states, which n-grams have prefix sig_ngram_prefix_p of length ngram_prefix_sz, are enumerated. If ngram_prefix_sz is 0, then sig_ngram_prefix_p can be NULL.

The process of enumeration is a repeated calling callback function callback_func, to which an action choice state n-gram 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_storage_enum_states will report success. If the callback function returns a negative value, then the process of enumeration will be terminated, and the function qsmm_storage_enum_states will report failure.

In the current implementation, the function qsmm_storage_enum_states does not support recursive calling from the callback function for the same storage.

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_CALLBACK

The callback function did return an error.

QSMM_ERR_STORAGE

Storage failure. See Getting the Reason of a Storage Failure, for information on how to get the reason of the failure.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

The type of the pointer to a callback function called for every enumerated action choice state is described below.

Data type: qsmm_enum_states_callback_func_t

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

typedef int (*qsmm_enum_states_callback_func_t)(
    qsmm_storage_t storage,
    int ngram_sz,
    const qsmm_sig_t *sig_ngram_p,
    void *paramp);

The callback function is called for every enumerated action choice state of storage. The list of signal identifiers of an action choice state is passed via argument sig_ngram_p, and the length of the list is passed via argument ngram_sz. A user parameter is passed via argument paramp.

The callback function might 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 enumerate cycle types for an action choice state, i.e. output signals, where each output signal along with the action choice state makes up a cycle type, the following function can be used.

Function: int qsmm_get_storage_cycle_next (qsmm_storage_t storage, int ngram_sz, const qsmm_sig_t *sig_ngram_p, qsmm_sig_t *sig_cycle_next_p)

This function retrieves the next cycle type, information on which is held in storage. The next cycle type is retrieved for an action choice state specified by list of signal identifiers sig_ngram_p of length ngram_sz. The next cycle type is represented by an output signal, which along with the action choice state makes up a cycle type.

When calling the function, *sig_cycle_next_p must contain an output signal for which it is necessary to obtain an output signal that corresponds to the next cycle type.

If *sig_cycle_next_p is equal to QSMM_SIG_INVALID, then on successful function completion *sig_cycle_next_p will contain an output signal that corresponds to the first cycle type for the action choice state.

If *sig_cycle_next_p is not equal to QSMM_SIG_INVALID, then on successful function completion *sig_cycle_next_p will contain an output signal greater than output signal *sig_cycle_next_p specified when calling the function, which corresponds to the next cycle type for the action choice state.

The first (or the next) output signal retrieved corresponds to the first (or to the next) cycle type, information on which is held in storage. If there is no such cycle type found, then *sig_cycle_next_p will be set to QSMM_SIG_INVALID.

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_NGRAM

Storage does not support holding information on an action choice state n-gram specified by arguments sig_ngram_p and ngram_sz.

QSMM_ERR_STORAGE

Storage failure. See Getting the Reason of a Storage Failure, for information on how to get the reason of the failure.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.


Next: , Previous: , Up: Statistics Storage   [Contents][Index]