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


3.3 Reading and Writing Statistics

To read and write a condition for an action choice state, the following functions can be used.

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 reads from a storage a condition for an action choice state specified by list of signal identifiers sig_ngram_p of length ngram_sz. If state_p is not NULL, then the condition will be copied to *state_p. If sspur_p is not NULL, then conditions for spur of supported types will be copied 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.

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.

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 a condition for an action choice state specified by list of signal identifiers sig_ngram_p of length ngram_sz. If state_p is not NULL, then condition *state_p will be copied to storage. If sspur_p is not NULL, then conditions for spur of supported types will be copied to storage from an array addressed by sspur_p. The number of array elements copied is returned by the function qsmm_get_storage_nspur.

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.

To update a condition for an action choice state, you first need to read an existing condition using the function qsmm_get_storage_state_stats, then set values of some fields, and finally write the condition using the function qsmm_set_storage_state_stats. For example, updating parameters of a probability profile for an action choice state to new values nsig_pos and nsig_ctrl could be performed using a block of code like this:

struct qsmm_state_s state;
if (qsmm_get_storage_state_stats(storage, ngram_sz, sig_ngram_p,
                                 &state, 0)<0)
    goto Error;
state.nsig_pos=nsig_pos;
state.nsig_ctrl=nsig_ctrl;
if (qsmm_set_storage_state_stats(storage, ngram_sz, sig_ngram_p,
                                 &state, 0)<0)
    goto Error;

To read and write statistics for a cycle type, the following functions can be used.

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_next, struct qsmm_cycle_s *cycle_p, struct qsmm_cspur_s *cspur_p)

This function reads statistics for a cycle type from storage. The cycle type is represented by an action choice state, specified by list of signal identifiers sig_ngram_p of length ngram_sz, and by a cycle direction specified by signal sig_cycle_next.

If cycle_p is not NULL, then the statistics will be copied to *cycle_p. If cspur_p is not NULL, then statistics for spur of supported types will be copied 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.

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.

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_next, const struct qsmm_cycle_s *cycle_p, const struct qsmm_cspur_s *cspur_p)

This function writes statistics for a cycle type to storage. The cycle type is represented by an action choice state, specified by list of signal identifiers sig_ngram_p of length ngram_sz, and by a cycle direction specified by signal sig_cycle_next.

If cycle_p is not NULL, then statistics *cycle_p will be copied to storage. If cspur_p is not NULL, then statistics for spur of supported types will be copied to storage from an array addressed by cspur_p. The number of array elements copied is returned by the function qsmm_get_storage_nspur.

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.

To update statistics for a cycle type, you first need to read statistics using the function qsmm_get_storage_cycle_stats, then set values of some fields, and finally write statistics using the function qsmm_set_storage_cycle_stats. For example, updating a profile probability5 for a cycle type to a new value profile could be performed using a block of code like this:

struct qsmm_cycle_s cycle;
if (qsmm_get_storage_cycle_stats(storage, ngram_sz, sig_ngram_p,
                                 sig_cycle_next, &cycle, 0)<0)
    goto Error;
cycle.profile=profile;
if (qsmm_set_storage_cycle_stats(storage, ngram_sz, sig_ngram_p,
                                 sig_cycle_next, &cycle, 0)<0)
    goto Error;

In the current version of the package storage is used to hold statistics for action choice state n-grams of fixed length. However, as you might see, functions that read and write statistics as well as some other functions, which belong to the Storage API, take the argument ngram_sz that specifies the length of action choice state n-gram. This argument is reserved for future use in the sense that in the future single storage can be used to hold statistics for action choice state n-grams of varying lengths.

To speed up program operation, Storage API functions perform minimal checks on the validity of their arguments. When the arguments have invalid values, program behavior is undefined.

To remove information on an action choice state from storage, the following function can be used.

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 specified by list of signal identifiers sig_ngram_p of length ngram_sz. The information includes a condition for the action choice state and statistics for all types of cycles that start at the action choice state. For map storage, memory allocated for holding this information is freed.

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_NOTFOUND

Information on the action choice state n-gram specified by arguments sig_ngram_p and ngram_sz not found in storage, nothing to remove.

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.


Footnotes

(5)

A profile probability does not fall into the category “statistics,” but it is stored along with statistics for a cycle type.


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