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


3.5 Providing Initial Statistics

Before the first use, instances of structures qsmm_state_s, qsmm_sspur_s, qsmm_cycle_s, and qsmm_cspur_s, which hold conditions for action choice states and statistics for cycle types, are initialized by Storage API functions with zeroes with the help of function memset. For every instance of structure qsmm_state_s, the following assignments are also performed: values of fields tmd0 and tmc0 are set to -1, and the value of field sig_cycle_next is set to QSMM_SIG_INVALID.

An application program can provide functions, which will be called by Storage API functions at time of initialization of the instances, and which may perform application-specific initialization. Those functions will be called during operations of access to a condition for an action choice state or statistics for a cycle type when storage does not contain requested information about the action choice state or the cycle type.

Functions, which perform application-specific initialization, may e.g. set parameters of a probability profile for an action choice state. They may also call Storage API functions for other action choice states, e.g. to copy 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 that performs application-specific initialization of condition of an action choice state. To this type the following declaration corresponds:

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);

Upon function call, *state_p and array sspur_p contain preinitialized values. The function can set *state_p and/or elements of array sspur_p to application-specific initial condition for an action choice state of storage. The action choice state is specified by list of signal identifiers sig_ngram_p of length ngram_sz. Elements of array sspur_p correspond to spur types supported by storage. The number of those elements is returned by the function qsmm_get_storage_nspur. Argument paramp is a user parameter specified when setting the redirection function.

The function must return a non-negative value on success or one of the following negative error codes on failure.

QSMM_ERR_STORAGE

Storage failure. The storage message list is expected to contain a message that describes the reason of the failure. See Getting the Reason of a Storage Failure, for more information on storage message list.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

To retrieve or set a redirection function, which performs application-specific initialization of a condition for an action choice state, the following functions can be used.

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 redirection function (previously set), which performs application-specific initialization of conditions for action choice states that could be held in storage. If get_state_stats_func_p is not NULL, then *get_state_stats_func_p will be set to a pointer to that redirection function or to 0 if there is no such function assigned to the storage. If param_pp is not NULL, then *param_pp will be set to a user parameter of that redirection function specified when assigning the redirection function to the storage. The function qsmm_get_storage_state_stats_redir shall return 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, which performs application-specific initialization of conditions for action choice states that could be held in storage. A pointer to the redirection function is specified by argument get_state_stats_func. A user parameter of the redirection function is specified by argument paramp. If get_state_stats_func is NULL, then no redirection function, which performs application-specific initialization of conditions for action choice states, will be used for the storage. The function qsmm_set_storage_state_stats_redir shall return a non-negative value.

Data type: qsmm_get_cycle_stats_func_t

This is the type of a pointer to a redirection function that performs application-specific initialization of statistics of a cycle type. To this type the following declaration corresponds:

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

Upon function call, *cycle_p and array cspur_p contain preinitialized values. The function can set *cycle_p and/or elements of array cspur_p to application-specific initial statistics for a cycle type of storage. The cycle type is specified by an action choice state and output signal sig_cycle_next that indicates a cycle direction. The action choice state is specified by list of signal identifiers sig_ngram_p of length ngram_sz. Elements of array cspur_p correspond to spur types supported by storage. The number of those elements is returned by the function qsmm_get_storage_nspur. Argument paramp is a user parameter specified when setting the redirection function.

The function must return a non-negative value on success or one of the following negative error codes on failure.

QSMM_ERR_STORAGE

Storage failure. The storage message list is expected to contain a message that describes the reason of the failure. See Getting the Reason of a Storage Failure, for more information on storage message list.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

To retrieve or set a redirection function, which performs application-specific initialization of statistics for a cycle type, the following functions can be used.

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 redirection function, which performs application-specific initialization of statistics for cycle types that could be held in storage. If get_cycle_stats_func_p is not NULL, then *get_cycle_stats_func_p will be set to a pointer to that redirection function or to 0 if there is no such function assigned to the storage. If param_pp is not NULL, then *param_pp will be set to a user parameter of that redirection function specified when assigning the redirection function to the storage. The function qsmm_get_storage_cycle_stats_redir shall return 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, which performs application-specific initialization of statistics for cycle types that could be held in storage. A pointer to the redirection function is specified by argument get_cycle_stats_func. A user parameter of the redirection function is specified by argument paramp. If get_cycle_stats_func is NULL, then no redirection function, which performs application-specific initialization of statistics for cycle types, will be used for the storage. The function qsmm_set_storage_cycle_stats_redir shall return a non-negative value.

When there is used a redirection function, which performs application-specific initialization of statistics for cycle types, it may be necessary to provide a redirection function, which returns the next type of cycles that start at an action choice state. The latter redirection function will provide correct enumeration of cycle types, which have profile probabilities assigned, in case of when those probabilities are supplied by external means (e.g. in a situation when an action choice state uses another action choice state as the source of probability profile).

Data type: qsmm_get_cycle_next_func_t

This is the type of a pointer to a redirection function that returns the next cycle type for an action choice state. To this type the following declaration corresponds:

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);

An action choice state, information on which is held in storage, is specified by list of signal identifiers sig_ngram_p of length ngram_sz. Upon function call, *sig_cycle_next_p contains an output signal for which it is necessary to obtain an output signal that corresponds to the next cycle type. If *sig_cycle_next_p is equal to QSMM_SIG_INVALID, then on successfully performed redirection, *sig_cycle_next_p must contain an output signal that corresponds to the first cycle type for the action choice state. If *sig_cycle_next_p is not equal to QSMM_SIG_INVALID, then on successfully performed redirection, *sig_cycle_next_p must contain an output signal greater than output signal *sig_cycle_next_p passed upon the function call, which corresponds to the next cycle type for the action choice state. If such the first or the next cycle type is not found, then *sig_cycle_next_p must be set to QSMM_SIG_INVALID. Argument paramp is a user parameter specified when setting the redirection function.

If the function successfully performs the redirection and possibly updates output signal *sig_cycle_next_p, then it must return a positive value. If the function does not perform the redirection, then it must return 0, so the next cycle type will be retrieved by the function qsmm_get_storage_cycle_next without the redirection. On failure, the function must return one of the following negative error codes.

QSMM_ERR_STORAGE

Storage failure. The storage message list is expected to contain a message that describes the reason of the failure. See Getting the Reason of a Storage Failure, for more information on storage message list.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

To retrieve or set a redirection function, which returns the next type of cycles that start at an action choice state, the following functions can be used.

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 redirection function that returns the next type of cycles, which start at an action choice state and information on which is held in storage. If get_cycle_next_func_p is not NULL, then *get_cycle_next_func_p will be set to a pointer to that redirection function or to 0 if there is no such function assigned to the storage. If param_pp is not NULL, then *param_pp will be set to a user parameter of that redirection function specified when assigning the redirection function to the storage. The function qsmm_get_storage_cycle_next_redir shall return 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 that returns the next type of cycles, which start at an action choice state and information on which is held in storage. A pointer to the redirection function is specified by argument get_cycle_next_func. A user parameter of the redirection function is specified by argument paramp. If get_cycle_next_func is NULL, then no redirection function that returns the next type of cycles, which start at an action choice state, will be used for the storage. The function qsmm_set_storage_cycle_next_redir shall return a non-negative value.


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