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

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`

`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 probability^{4} 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`

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

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.