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


3.3 Retrieving and Storing 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_sspur_s *sspur_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 sspur_p is not NULL, the function copies conditions for all spur types associated with the action choice state to an array addressed by sspur_p. The array must be capable of holding the number of elements returned by the function qsmm_get_storage_nspur.

If the storage does not contain the condition of the action choice state, and the storage has a set redirection function for retrieving the initial condition of an action choice state, the function qsmm_get_storage_state_stats calls this 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 this redirection function, the function qsmm_get_storage_state_stats may also call a redirection function for retrieving the initial statistics of a cycle type. See Providing Initial Statistics, for more information on those redirection functions.

If the storage contained the condition of the action choice state, or the storage did not contain the condition, but the redirection function has retrieved it, qsmm_get_storage_state_stats returns a positive value. If the 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 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 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 this redirection function is 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 is 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_sspur_s *sspur_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 sspur_p is not NULL, the function copies conditions for all spur types associated with the action choice state from an array addressed by sspur_p. The function qsmm_get_storage_nspur returns the number of elements of sspur_p array copied.

The function qsmm_set_storage_state_stats may call a redirection function for obtaining the initial condition of an action choice state when adding information on it to the 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 Providing Initial Statistics, for more information on those 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

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 function qsmm_get_storage_cycle_stats called to validate the field sig_cycle_next of *state_p or 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 a redirection function for retrieving the initial condition of an action choice state reported QSMM_ERR_STATS, or condition retrieved by the redirection function is inconsistent.

Condition in qsmm_state_s is inconsistent in the following cases:

  • nsig_pos is equal to 1;
  • nsig_pos is negative, but -nsig_pos-1 is not an output signal of an actor owning the storage;
  • nsig_pos is greater than 1, but nsig_ctrl is less than or equal to 1 or greater than nsig_pos;
  • 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, and tmc0 is negative;
  • sig_cycle_next is not QSMM_SIG_INVALID, nsig_pos is not 0, 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.
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 is not convertible to a wide string according to a current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

On errors QSMM_ERR_STORAGE, QSMM_ERR_STATS, QSMM_ERR_ILSEQ, and QSMM_ERR_NOMEM, the function may leave the condition of the action choice state updated in an unexpected way.

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 update the parameters of the probability profile of an action choice state to new values nsig_pos and nsig_ctrl 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.nsig_pos=nsig_pos;
state.nsig_ctrl=nsig_ctrl;
if ((rc=
     qsmm_set_storage_state_stats(storage, ngram_sz, sig_ngram_p,
                                  &state, 0))<0)
    REPORT_ERROR(rc);

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_cspur_s *cspur_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 cspur_p is not NULL, the function copies statistics on all spur types associated with the cycle type to an array addressed by cspur_p. The array must be capable of holding the number of elements returned by the function qsmm_get_storage_nspur.

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

If the storage contained statistics on the cycle type, or the storage did not contain the statistics, but the redirection function has retrieved it, qsmm_get_storage_cycle_stats returns a positive value. If the 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 signal 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 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 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 this redirection function is 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 is 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_cspur_s *cspur_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 cspur_p is not NULL, the function copies statistics for all spur types associated with the cycle type from an array addressed by cspur_p. The function qsmm_get_storage_nspur returns the number of elements of cspur_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 the storage has such redirection function set. See Intercepting the Updates of Cycle Type Statistics, for more information on this redirection function. The function qsmm_set_storage_cycle_stats may call redirection functions for obtaining the initial condition of an action choice state or the initial statistics of a cycle type when adding information on it to the storage. See Providing Initial Statistics, for more information on these 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 signal 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 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

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 a storage redirection function reported QSMM_ERR_STATS, or statistics obtained from a storage redirection function is inconsistent.

Statistics in qsmm_cycle_s is inconsistent in the following cases:

  • fq is negative;
  • period_sum_d is negative;
  • period_sum_c is negative;
  • profile is negative or greater than 1;
  • fq is zero, but period_sum_d is positive;
  • fq is zero, but period_sum_c is positive.
QSMM_ERR_ILSEQ

A 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.

On errors QSMM_ERR_STORAGE, QSMM_ERR_STATS, QSMM_ERR_ILSEQ, and QSMM_ERR_NOMEM, the function may leave the condition of the action choice state or the statistics of the cycle type updated in an unexpected way.

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 probability4 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 this action choice state and statistics on all types of cycles starting at the action choice state. For map storage, the function frees memory allocated for holding that information.

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_NOTFOUND

Information on the action choice state not found in the storage—nothing to remove.


Footnotes

(4)

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


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