Next: Getting the Reason of a Storage Failure, Previous: Providing Initial Statistics, Up: Statistics Storage [Contents][Index]

Intercepting the updates of statistics on cycle types may be necessary to organize keeping this statistics only for latest events in an event history rather than for the entire event history. Keeping statistics just for the tail of the event history may improve the response of a system to latest tendencies in the event history. Using a different methodology, by making a state model less stable, the system can try more state model variations and then select a variation that occurs more frequently.

The function `qsmm_set_storage_cycle_stats`

calls a storage redirection function for intercepting the updates of statistics on cycle types if storage has such redirection function set.
The type of a pointer to the redirection function is below.

- Data type:
**qsmm_update_cycle_stats_func_t** This is the type of a pointer to a redirection function for intercepting the updates of statistics on cycle types. The pointer type has the following declaration:

typedef int (*qsmm_update_cycle_stats_func_t)( 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_new_p, struct qsmm_cycle_s *cycle_result_p, const struct qsmm_cspur_s *cspur_new_p, struct qsmm_cspur_s *cspur_result_p, void *paramp );

The argument

`storage`is a storage handle with this redirection function set passed to the function`qsmm_set_storage_cycle_stats`

. An action choice state and output signal`sig_cycle`indicating a cycle direction specify a cycle type. An array of signal identifiers`sig_ngram_p`holding`ngram_sz`elements encodes the action choice state.New statistics on the cycle type is in *

`cycle_new_p`and the array`cspur_new_p`. On calling the function, current statistics on the cycle type is in *`cycle_result_p`and the array`cspur_result_p`. The arrays`cspur_new_p`and`cspur_result_p`hold the number of elements returned by the function`qsmm_get_storage_nspur`

. The redirection function can compute the difference between *`cycle_new_p`and *`cycle_result_p`and between the elements of`cspur_new_p`and`cspur_result_p`.To directly use *

`cycle_result_p`and the array`cspur_result_p`as the new statistics on the cycle type, the function shall return a positive value; in this case, the function can change *`cycle_result_p`and the array`cspur_result_p`in its own way. To replace *`cycle_result_p`with *`cycle_new_p`, replace the elements of`cspur_result_p`with the elements of`cspur_new_p`, and use *`cycle_result_p`and the array`cspur_result_p`as the new statistics on the cycle type, the function shall return 0. On failure, the function shall return one of the following negative error codes.`QSMM_ERR_STORAGE`

Storage failure. Before reporting this error, the function shall add to the storage message list at least one message describing the reason of the failure. See Getting the Reason of a Storage Failure, for more information on the storage message list.

`QSMM_ERR_STATS`

Inconsistent statistics on an action choice state or cycle type detected.

`QSMM_ERR_ILSEQ`

Unable to convert a multibyte string to a wide string or vice versa according to a current locale.

`QSMM_ERR_NOMEM`

There was not enough memory to perform the operation.

To organize keeping statistics on cycle types for the event history tail, a storage redirection function intercepting the updates of statistics on cycle types keeps a queue of records, where every record contains the following information about an update of statistics on a cycle type:

- – time of the update;
- – an action choice state and a cycle direction specifying the cycle type;
- – increments to the fields
`fq`

,`period_sum_d`

, and`period_sum_c`

of`qsmm_cycle_s`

structure and the field`delta_sum`

in the elements of an array of`qsmm_cspur_s`

structures; - – increments to spur accumulated by the actor relative to the previous update.

The redirection function does the following:

- Prevents recursive calls to itself when calling the function
`qsmm_set_storage_cycle_stats`

to decrement statistics on cycle types. - Removes too old records from the queue with decrementing statistics on cycle types specified by removed records and with decrementing spur accumulated by the actor. A removed record contains differences to statistics on the cycle type and a difference to spur tracked by the actor relative to the previously added record. After removing the old records, storage contains statistics on cycle types and the actor holds spur only for the event history tail.
- Adds a new record to the queue.

Use the following functions to retrieve or set a redirection function for intercepting the updates of statistics on cycle types.

- Function:
*int***qsmm_get_storage_cycle_update_hook***(qsmm_storage_t*`storage`, qsmm_update_cycle_stats_func_t *`update_cycle_stats_func_p`, void **`param_pp`) This function retrieves a previously set redirection function for intercepting the updates of statistics on cycle types by the function

`qsmm_set_storage_cycle_stats`

called for`storage`. If`update_cycle_stats_func_p`is not`NULL`

, the function`qsmm_get_storage_cycle_update_hook`

sets *`update_cycle_stats_func_p`to a pointer to the redirection function or to`NULL`

if the storage does not have such function assigned. If`param_pp`is not`NULL`

,`qsmm_get_storage_cycle_update_hook`

sets *`param_pp`to a user parameter of that redirection function specified when assigning it to the storage. The function`qsmm_get_storage_cycle_update_hook`

returns a non-negative value.

- Function:
*int***qsmm_set_storage_cycle_update_hook***(qsmm_storage_t*`storage`, qsmm_update_cycle_stats_func_t`update_cycle_stats_func`, void *`paramp`) This function sets a redirection function for intercepting the updates of statistics on cycle types by the function

`qsmm_set_storage_cycle_stats`

called for`storage`. The argument`update_cycle_stats_func`specifies a pointer to the redirection function. The argument`paramp`specifies the user parameter of that redirection function. If`update_cycle_stats_func`is`NULL`

, then the storage will not use a redirection function for intercepting the updates of statistics on cycle types. The function`qsmm_set_storage_cycle_update_hook`

returns a non-negative value.