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


3.5 Providing Initial Statistics

Before first use, Storage API functions initialize by the function memset with zeroes the instances of qsmm_state_s, qsmm_sspur_s, qsmm_cycle_s, and qsmm_cspur_s structures holding conditions for action choice states and statistics on cycle types. For every instance of qsmm_state_s structure, the Storage API functions also perform the following assignments: set the fields tmd0 and tmc0 to -1 and the field sig_cycle_next to QSMM_SIG_INVALID.

An application program can provide redirection functions called by the Storage API functions just after the above initialization. Those redirection functions may perform application-specific initialization. The Storage API functions will call those functions on accessing condition for an action choice state or statistics on a cycle type when storage does not contain requested information about the action choice state or the cycle type.

Storage redirection functions performing application-specific initialization may set the parameters of a probability profile for an action choice state. They may also call Storage API functions for other action choice states, for example, to copy the parameters of a probability profile from another action choice state.

Data type: qsmm_get_state_stats_func_t

This is the type of a pointer to a redirection function for application-specific initialization of condition of an action choice state. The type has the following declaration:

typedef int
(*qsmm_get_state_stats_func_t)(
    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,
    void *paramp
);

The argument storage is a storage handle with this redirection function set. On calling this function, *state_p and the array sspur_p contain preinitialized values. The function can set *state_p and/or elements of sspur_p array to application-specific initial condition for an action choice state. An array of signal identifiers sig_ngram_p holding ngram_sz elements encodes the action choice state. The elements of sspur_p array correspond to spur types supported by the storage. The function qsmm_get_storage_nspur returns the number of those elements in the array. The argument paramp is a user parameter specified when setting the redirection function for the storage.

If the function has performed the redirection and possibly modified the preinitialized values in *state_p or the array sspur_p, the function shall return a positive result. If the function has not performed the redirection and has left those preinitialized values intact, 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.

Use the following functions to retrieve or set a redirection function for application-specific initialization of condition of an action choice state.

Function: int qsmm_get_storage_state_stats_redir (qsmm_storage_t storage, qsmm_get_state_stats_func_t *get_state_stats_func_p, void **param_pp)

This function retrieves a previously set redirection function for application-specific initialization of conditions of action choice states in storage. If get_state_stats_func_p is not NULL, the function qsmm_get_storage_state_stats_redir sets *get_state_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_state_stats_redir sets *param_pp to a user parameter of that redirection function specified when assigning it to the storage. The function qsmm_get_storage_state_stats_redir returns a non-negative value.

Function: int qsmm_set_storage_state_stats_redir (qsmm_storage_t storage, qsmm_get_state_stats_func_t get_state_stats_func, void *paramp)

This function sets a redirection function for application-specific initialization of conditions of action choice states in storage. The argument get_state_stats_func specifies a pointer to the redirection function. The argument paramp specifies the user parameter of that redirection function. If get_state_stats_func is NULL, then the storage will not use a redirection function for application-specific initialization of conditions of action choice states. The function qsmm_set_storage_state_stats_redir returns a non-negative value.

Data type: qsmm_get_cycle_stats_func_t

This is the type of a pointer to a redirection function for application-specific initialization of statistics on a cycle type. The pointer type has the following declaration:

typedef int
(*qsmm_get_cycle_stats_func_t)(
    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,
    void *paramp
);

The argument storage is a storage handle with this redirection function set. On calling this function, *cycle_p and the array cspur_p contain preinitialized values. The function can set *cycle_p and/or elements of cspur_p array to application-specific initial statistics on a cycle type. An action choice state and output signal sig_cycle indicating a cycle direction specify the cycle type. An array of signal identifiers sig_ngram_p holding ngram_sz elements encodes the action choice state. The elements of cspur_p array correspond to spur types supported by the storage. The function qsmm_get_storage_nspur returns the number of those elements in the array. The argument paramp is a user parameter specified when setting the redirection function for the storage.

If the function has performed the redirection and possibly modified the preinitialized values in *cycle_p or the array cspur_p, the function shall return a positive result. If the function has not performed the redirection and has left those preinitialized values intact, 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.

Use the following functions to retrieve or set a redirection function for application-specific initialization of statistics on a cycle type.

Function: int qsmm_get_storage_cycle_stats_redir (qsmm_storage_t storage, qsmm_get_cycle_stats_func_t *get_cycle_stats_func_p, void **param_pp)

This function retrieves a previously set redirection function for application-specific initialization of statistics on cycle types in storage. If get_cycle_stats_func_p is not NULL, the function qsmm_get_storage_cycle_stats_redir sets *get_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_stats_redir sets *param_pp to a user parameter of that redirection function specified when assigning it to the storage. The function qsmm_get_storage_cycle_stats_redir returns a non-negative value.

Function: int qsmm_set_storage_cycle_stats_redir (qsmm_storage_t storage, qsmm_get_cycle_stats_func_t get_cycle_stats_func, void *paramp)

This function sets a redirection function for application-specific initialization of statistics on cycle types in storage. The argument get_cycle_stats_func specifies a pointer to the redirection function. The argument paramp specifies the user parameter of that redirection function. If get_cycle_stats_func is NULL, then the storage will not use a redirection function for application-specific initialization of statistics on cycle types. The function qsmm_set_storage_cycle_stats_redir returns a non-negative value.

If an application sets a redirection function for custom initialization of statistics on cycle types, the application may need to provide a redirection function for retrieving the next cycle type for an action choice state. The latter redirection function will enable correct enumeration of cycle types with initial statistics provided by the former redirection function. Enumerating cycle types that do not yet have information in storage is necessary for generating the probability profiles of action choice states on demand—on read access to information on action choice states and their cycle types before the first write access to this information.

Data type: qsmm_get_cycle_next_func_t

This is the type of a pointer to a redirection function for retrieving the next cycle type for an action choice state. The pointer type has the following declaration:

typedef int
(*qsmm_get_cycle_next_func_t)(
    qsmm_storage_t storage,
    int ngram_sz,
    const qsmm_sig_t *sig_ngram_p,
    qsmm_sig_t *sig_cycle_next_p,
    void *paramp
);

The argument storage is a storage handle with this redirection function set passed to the function qsmm_get_storage_cycle_next. The array of signal identifiers sig_ngram_p holding ngram_sz elements encodes the action choice state. The argument paramp is a user parameter specified when setting the redirection function for the storage.

If *sig_cycle_next_p is QSMM_SIG_INVALID, then on successfully performed redirection, *sig_cycle_next_p shall contain a minimum output signal that along with the action choice state specify the first cycle type for that action choice state. If *sig_cycle_next_p is not QSMM_SIG_INVALID, then on successfully performed redirection, *sig_cycle_next_p shall contain the next output signal greater than a signal specified in *sig_cycle_next_p when calling the redirection function; that output signal along with the action choice state shall specify the next cycle type for the action choice state. If the first or next cycle type does not exist, then on successful function completion, *sig_cycle_next_p shall be QSMM_SIG_INVALID.

If the function has performed the redirection and possibly updated *sig_cycle_next_p, the function shall return a positive value. If the function has not performed the redirection and has left *sig_cycle_next_p intact, the function shall return 0; in this case, qsmm_get_storage_cycle_next retrieves the next cycle type without the redirection. On failure, the redirection 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.

Use the following functions to retrieve or set a redirection function for obtaining the next cycle type for an action choice state.

Function: int qsmm_get_storage_cycle_next_redir (qsmm_storage_t storage, qsmm_get_cycle_next_func_t *get_cycle_next_func_p, void **param_pp)

This function retrieves a previously set redirection function for obtaining the next cycle type that has a piece of information in storage. If get_cycle_next_func_p is not NULL, the function qsmm_get_storage_cycle_next_redir sets *get_cycle_next_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_next_redir sets *param_pp to a user parameter of that redirection function specified when assigning it to the storage. The function qsmm_get_storage_cycle_next_redir returns a non-negative value.

Function: int qsmm_set_storage_cycle_next_redir (qsmm_storage_t storage, qsmm_get_cycle_next_func_t get_cycle_next_func, void *paramp)

This function sets a redirection function for obtaining the next cycle type that has a piece of information in storage. The argument get_cycle_next_func specifies a pointer to the redirection function. The argument paramp specifies the user parameter of that redirection function. If get_cycle_next_func is NULL, then the storage will not use a redirection function for obtaining the next cycle type. The function qsmm_set_storage_cycle_next_redir returns a non-negative value.


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