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


3.4 Enumerating Action Choice States and Cycle Types

Use the following function to enumerate action choice states that have pieces of information held in storage.

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

This function enumerates action choice states that have pieces of information held in storage. The function enumerates action choice states encoded by lists of signal identifiers that have a prefix sig_ngram_prefix_p with length ngram_prefix_sz. If ngram_prefix_sz is 0, then sig_ngram_prefix_p can be NULL.

The process of enumeration is repeated calling a callback function callback_func receiving an array of signal identifiers encoding an action choice state and receiving a user parameter paramp. If the callback function returns a positive value, the function qsmm_storage_enum_states continues the enumeration. If the callback function returns zero, qsmm_storage_enum_states terminates the enumeration and reports success. If the callback function returns a negative value, qsmm_storage_enum_states 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 ngram_prefix_sz is less than 0 or greater than the length of a list of signal identifiers encoding an action choice state.

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 action choice state is below.

Data type: qsmm_enum_state_callback_func_t

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

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

The function qsmm_storage_enum_states calls the callback function for every enumerated action choice state of storage. The argument sig_ngram_p specifies an array of signal identifiers encoding an action choice state. The argument ngram_sz specifies the length of this array. The argument paramp is a user parameter passed to qsmm_storage_enum_states.

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.

Use a function described below to enumerate the types of cycles starting at an action choice state. A cycle direction and the action choice state make up an enumerated cycle type.

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 that has a piece of information held in storage. An action choice state and a cycle direction specify the cycle type. An array of signal identifiers sig_ngram_p holding ngram_sz elements encodes the action choice state.

If *sig_cycle_next_p is QSMM_SIG_INVALID, then on successful function completion, *sig_cycle_next_p will contain the first minimum cycle direction. If *sig_cycle_next_p is not QSMM_SIG_INVALID, then on successful function completion, *sig_cycle_next_p will contain the next cycle direction greater than a cycle direction specified in *sig_cycle_next_p when calling the function. If the first or next cycle direction does not exist, then on successful function completion, *sig_cycle_next_p will be QSMM_SIG_INVALID.

If the storage has a set redirection function for retrieving the next cycle type of an action choice state, the function qsmm_get_storage_cycle_next calls the redirection function to obtain the next cycle type. If the redirection function reports that it has not retrieved the next cycle type, qsmm_get_storage_cycle_next proceeds as if the storage does not have such redirection function set.

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 storage does not support length ngram_sz for arrays of signal identifiers encoding action choice states.

QSMM_ERR_NGRAM

The storage does not support holding information on an action choice state encoded using sig_ngram_p and valid ngram_sz. A set of action choice states supported by storage is equal to a set of action choice states supported by an actor owning the storage.

QSMM_ERR_STORAGE

The storage redirection function reported QSMM_ERR_STORAGE or an unexpected error code. See Getting the Reason of a Storage Failure, for how to get an error message describing the failure.

QSMM_ERR_STATS

The storage redirection function reported QSMM_ERR_STATS, or a cycle direction obtained by that redirection function is not QSMM_SIG_INVALID and is not an output signal of an actor owning the storage.

QSMM_ERR_ILSEQ

The storage redirection function reported QSMM_ERR_ILSEQ, or a generated error message is not convertible to a wide string according to a current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.


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