Retrieving Storing and Removing Statistics (QSMM Programmer Manual)

Next: Enumerating Action Choice States and Cycle Types, Previous: Structures for Accessing Storage, Up: Statistics Storage [Contents][Index]

3.3 Retrieving, Storing, and Removing Statistics ¶

Use the following functions to retrieve or store the condition of an action choice state.

Function: int qsmm_get_storage_state_stats (qsmm_storage_t storage, int ngram_sz, const qsmm_sig_t *sig_ngram_p, struct qsmm_state_s *state_p, struct qsmm_sspval_s *sspval_p) ¶

This function retrieves from storage the condition of an action choice state encoded by an array of signal identifiers sig_ngram_p holding ngram_sz elements. If state_p is not NULL, the function copies the condition to *state_p. If sspval_p is not NULL, the function copies conditions for all cycle-summed value types associated with the action choice state to an array addressed by sspval_p. The array must be capable of holding the number of elements returned by the function qsmm_get_storage_nspval.

If storage does not contain the condition of the action choice state, and storage has a set redirection function for retrieving the initial condition of an action choice state, qsmm_get_storage_state_stats calls the redirection function to obtain the initial condition of the action choice state. When validating the field sig_cycle_next of qsmm_state_s structure obtained by the redirection function, qsmm_get_storage_state_stats may also call a redirection function for retrieving the initial statistics of a cycle type. See Specifying Redirection Functions, for more information on the redirection functions.

If storage contained the condition of the action choice state, or storage did not contain the condition, but the redirection function has retrieved it, qsmm_get_storage_state_stats returns a positive value. If storage did not contain the condition, and the redirection function has not retrieved it, qsmm_get_storage_state_stats returns 0 and the constant default condition. On failure, qsmm_get_storage_state_stats returns a negative error code. Currently, this 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 by the array sig_ngram_p. A set of action choice states supported by storage is a set of action choice states supported by an actor owning the storage.

QSMM_ERR_STORAGE

The storage did not contain the condition of the action choice state, and a redirection function called to obtain the initial condition of the action choice state has reported QSMM_ERR_STORAGE or an unexpected error code, or the redirection function succeeded, but the function qsmm_get_storage_cycle_stats called to validate the field sig_cycle_next of qsmm_state_s structure obtained by that redirection function has reported QSMM_ERR_STORAGE.

See Getting the Reason of a Storage Failure, for how to get an error message describing the failure.

QSMM_ERR_STATS

A redirection function for retrieving the initial condition of an action choice state reported QSMM_ERR_STATS, or condition retrieved by the redirection function was inconsistent.

QSMM_ERR_ILSEQ

A redirection function for retrieving the initial condition of an action choice state or the initial statistics of a cycle type reported QSMM_ERR_ILSEQ, or a generated error message was not convertible to a wide string according to a current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Function: int qsmm_set_storage_state_stats (qsmm_storage_t storage, int ngram_sz, const qsmm_sig_t *sig_ngram_p, const struct qsmm_state_s *state_p, const struct qsmm_sspval_s *sspval_p) ¶

This function writes to storage the condition of an action choice state encoded by an array of signal identifiers sig_ngram_p holding ngram_sz elements. If state_p is not NULL, the function copies the condition from *state_p. If sspval_p is not NULL, the function copies conditions for all cycle-summed value types associated with the action choice state from an array addressed by sspval_p. The function qsmm_get_storage_nspval returns the number of elements of sspval_p array copied.

The function qsmm_set_storage_state_stats may call a redirection function for obtaining the initial condition of the action choice state when adding information on it to storage. The function qsmm_set_storage_state_stats may also call a redirection function for obtaining the initial statistics of a cycle type when validating the field sig_cycle_next of qsmm_state_s structure. See Specifying Redirection Functions, for more information on the redirection functions.

The function qsmm_set_storage_state_stats 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

QSMM_ERR_STORAGE

The function qsmm_get_storage_cycle_stats called to validate the field sig_cycle_next of *state_p or validate the field sig_cycle_next of an instance of qsmm_state_s structure obtained by a redirection function for retrieving the initial condition of an action choice state reported QSMM_ERR_STORAGE, or the 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

Inconsistent condition in *state_p or an element of sspval_p array, or a redirection function for retrieving the initial condition of an action choice state reported QSMM_ERR_STATS, or condition retrieved by the redirection function was inconsistent.

Condition in qsmm_state_s is inconsistent in the following cases:

nsig_ctrl is not finite;
nsig_ctrl is negative;
the action choice state has a single cycle direction allowed by a probability profile, but nsig_ctrl is not 0 and 1;
the action choice state has multiple cycle directions allowed by a probability profile, and nsig_ctrl is not 0 but is less than or equal to 1 or is greater than the number of cycle directions allowed by the probability profile;
sig_cycle_next is not QSMM_SIG_INVALID but also not an output signal of an actor owning the storage;
sig_cycle_next is not QSMM_SIG_INVALID, and tmd0 is negative;
sig_cycle_next is not QSMM_SIG_INVALID, the action choice state has a probability profile assigned, and the function qsmm_get_storage_cycle_stats called to check the presence of statistics on a cycle type for the action choice state and cycle direction sig_cycle_next returned 0 or reported QSMM_ERR_STATS.

Condition in an element of sspval_p array is inconsistent if the field val0 of the element is not finite.

QSMM_ERR_ILSEQ

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

To update the condition of an action choice state, you first need to retrieve existing condition by the function qsmm_get_storage_state_stats, then change some fields, and, finally, store the condition by the function qsmm_set_storage_state_stats. For example, you can reset the field tmd in the condition of an action choice state using a block of code like this:

int rc;
struct qsmm_state_s state;
if ((rc=
     qsmm_get_storage_state_stats(storage, ngram_sz, sig_ngram_p,
                                  &state, 0))<0)
    REPORT_ERROR(rc);
state.tmd=-1;

if ((rc=
     qsmm_set_storage_state_stats(storage, ngram_sz, sig_ngram_p,
                                  &state, 0))<0)
    REPORT_ERROR(rc);

To satisfy validity checks performed by the function qsmm_set_storage_state_stats for the fields nsig_ctrl and sig_cycle_next of qsmm_state_s structure, a call to that function should go after a series of calls to the function qsmm_set_storage_cycle_stats described further on in this section. This is necessary because the validity checks depend on the value of nsig_pos field automatically calculated based on previous calls to qsmm_set_storage_cycle_stats. If nsig_pos is non-zero, sig_cycle_next should be QSMM_SIG_INVALID or specify the direction of a cycle type with statistics held in storage.

Use the following functions to retrieve or store statistics on a cycle type.

Function: int qsmm_get_storage_cycle_stats (qsmm_storage_t storage, int ngram_sz, const qsmm_sig_t *sig_ngram_p, qsmm_sig_t sig_cycle, struct qsmm_cycle_s *cycle_p, struct qsmm_cspval_s *cspval_p) ¶

This function retrieves statistics on a cycle type from storage. An action choice state and cycle direction sig_cycle specify the cycle type. An array of signal identifiers sig_ngram_p holding ngram_sz elements encodes the action choice state.

If cycle_p is not NULL, the function copies the statistics to *cycle_p. If cspval_p is not NULL, the function copies statistics on all cycle-summed value types associated with the cycle type to an array addressed by cspval_p. The array must be capable of holding the number of elements returned by the function qsmm_get_storage_nspval.

If storage does not contain statistics on the cycle type, and storage has a set redirection function for retrieving the initial statistics of a cycle type, qsmm_get_storage_cycle_stats calls the redirection function to obtain initial statistics on the cycle type. See Specifying Redirection Functions, for more information on the redirection function.

If storage contained statistics on the cycle type, or storage did not contain the statistics, but the redirection function has retrieved it, qsmm_get_storage_cycle_stats returns a positive value. If storage did not contain the statistics, and the redirection function has not retrieved it, qsmm_get_storage_cycle_stats returns 0 and zero statistics. On failure, qsmm_get_storage_cycle_stats returns a negative error code. Currently, this 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, or sig_cycle is not an output signal of an actor owning the storage.
QSMM_ERR_NGRAM: The storage does not support holding information on an action choice state encoded by the array sig_ngram_p. A set of action choice states supported by storage is a set of action choice states supported by an actor owning the storage.
QSMM_ERR_STORAGE: The storage did not contain statistics on the cycle type, and a redirection function called to obtain initial statistics on the cycle type has 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: A redirection function for retrieving the initial statistics of a cycle type reported QSMM_ERR_STATS, or statistics retrieved by the redirection function was inconsistent.
QSMM_ERR_ILSEQ: A redirection function for retrieving the initial statistics of a cycle type reported QSMM_ERR_ILSEQ, or a generated error message was not convertible to a wide string according to a current locale.
QSMM_ERR_NOMEM: There was not enough memory to perform the operation.

Function: int qsmm_set_storage_cycle_stats (qsmm_storage_t storage, int ngram_sz, const qsmm_sig_t *sig_ngram_p, qsmm_sig_t sig_cycle, const struct qsmm_cycle_s *cycle_p, const struct qsmm_cspval_s *cspval_p) ¶

This function writes statistics on a cycle type to storage. An action choice state and cycle direction sig_cycle specify the cycle type. An array of signal identifiers sig_ngram_p holding ngram_sz elements encodes the action choice state.

If cycle_p is not NULL, the function copies the statistics from *cycle_p. If cspval_p is not NULL, the function copies statistics for all cycle-summed value types associated with the cycle type from an array addressed by cspval_p. The function qsmm_get_storage_nspval returns the number of elements of cspval_p array copied.

The function qsmm_set_storage_cycle_stats calls a redirection function for the interception of updating statistics on a cycle type if storage has the redirection function set. See Specifying Redirection Functions, for more information on the redirection function. The function qsmm_set_storage_cycle_stats may call redirection functions for obtaining the initial condition of the action choice state or the initial statistics of the cycle type when adding information on it to storage. See Specifying Redirection Functions, for more information on the redirection functions.

The function qsmm_set_storage_cycle_stats 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, or sig_cycle is not an output signal of an actor owning the storage.

QSMM_ERR_NGRAM

QSMM_ERR_STORAGE

A 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

Inconsistent statistics in *cycle_p or an element of cspval_p array, or a storage redirection function reported QSMM_ERR_STATS, or statistics obtained from a storage redirection function was inconsistent.

Statistics in qsmm_cycle_s is inconsistent in the following cases:

fq is negative;
period_sum_d is negative;
profile is not finite;
profile is negative;
profile is greater than 1;
fq is zero, but period_sum_d is positive.

Statistics in an element of cspval_p array is inconsistent if the field delta_sum of the element is not finite.

QSMM_ERR_ILSEQ

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

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

To update statistics on a cycle type, you first need to retrieve existing statistics by the function qsmm_get_storage_cycle_stats, then change some fields, and, finally, store the statistics by the function qsmm_set_storage_cycle_stats. For example, you can update a profile probability² for a cycle type to a new value profile using a block of code like this:

int rc;
struct qsmm_cycle_s cycle;
if ((rc=
     qsmm_get_storage_cycle_stats(storage, ngram_sz, sig_ngram_p,
                                  sig_cycle, &cycle, 0))<0)
    REPORT_ERROR(rc);
cycle.profile=profile;

if ((rc=
     qsmm_set_storage_cycle_stats(storage, ngram_sz, sig_ngram_p,
                                  sig_cycle, &cycle, 0))<0)
    REPORT_ERROR(rc);

At present, an actor uses storage to hold statistics on action choice states encoded by arrays of signal identifiers with a fixed number of elements. The argument ngram_sz of Storage API functions must be equal to this fixed length. In the future, storage may hold statistics on action choice states encoded by arrays of signal identifiers with varying lengths, so that argument may have multiple valid values.

Use the following function to remove information on an action choice state from storage.

Function: int qsmm_storage_remove_state (qsmm_storage_t storage, int ngram_sz, const qsmm_sig_t *sig_ngram_p) ¶

This function removes from storage information on an action choice state encoded by an array of signal identifiers sig_ngram_p holding ngram_sz elements. The information includes the condition of the action choice state and statistics on all types of cycles starting at the action choice state.

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 by the array sig_ngram_p. A set of action choice states supported by storage is a set of action choice states supported by an actor owning the storage.
QSMM_ERR_NOTFOUND: Information on the action choice state not found in the storage—nothing to remove.

Footnotes

(2)

A profile probability does not fall into the category “statistics.” The structure qsmm_cycle_s holds a profile probability along with statistics on a cycle type.