Next: , Previous: , Up: Adaptive Probabilistic Mapping   [Contents][Index]


2.10 Revising Action Choice States

Revising action choice states includes enumerating and removing them. You may need to enumerate the action choice states of an actor to clear or update statistics on them. The following function enumerates action choice states that have pieces of information stored in the memory of an actor.

Function: int qsmm_actor_enum_ngrams (qsmm_actor_t actor, int ngram_prefix_sz, const qsmm_sig_t *sig_ngram_prefix_p, qsmm_enum_ngram_callback_func_t callback_func, void *paramp)

This function enumerates the lists of signal identifiers encoding action choice states that have pieces of information stored in the memory of an actor. For a small actor, those action choice states have pieces of information held in statistics storage with a handle retrievable by the function qsmm_get_actor_storage. For a large actor, those action choice states are the union of the following state sets:

The function qsmm_actor_enum_ngrams enumerates the aforementioned action choice states encoded by the lists of signal identifiers with a prefix sig_ngram_prefix_p that has length ngram_prefix_sz. If ngram_prefix_sz is 0, then sig_ngram_prefix_p can be NULL.

The process of enumeration is repeated calling a callback function callback_func. The callback function receives a user parameter paramp and an array of signal identifiers encoding an enumerated action choice state. If the callback function returns a positive value, qsmm_actor_enum_ngrams continues the enumeration. If the callback function returns zero, qsmm_actor_enum_ngrams terminates the enumeration and reports success. If the callback function returns a negative value, qsmm_actor_enum_ngrams terminates the enumeration and reports failure.

The function qsmm_actor_enum_ngrams does not support recursive calling from the callback function for the same actor.

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 argument ngram_prefix_sz is less than 0 or greater than the length of a list of signal identifiers encoding an action choice state.

QSMM_ERR_CALLBACK

The callback function reported an error.

QSMM_ERR_STORAGE

Failure of statistics storage of a large actor. See Getting the Reason of a Storage Failure, for how to get an error message describing the failure.

QSMM_ERR_STATS

Inconsistent statistics on an action choice state or cycle type detected for a large actor.

QSMM_ERR_ILSEQ

For a large actor, a generated error message is not convertible to a wide string according to a current locale, or a storage redirection function reported QSMM_ERR_ILSEQ.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

The type of a pointer to a callback function called for every enumerated action choice state is below.

Data type: qsmm_enum_ngram_callback_func_t

This is a type of a callback function pointer with the following declaration:

typedef int
(*qsmm_enum_ngram_callback_func_t)(
    qsmm_actor_t actor,
    const qsmm_sig_t *sig_ngram_p,
    void *paramp
);

The function qsmm_actor_enum_ngrams calls the callback function for every enumerated action choice state of an actor. The argument sig_ngram_p specifies an array of signal identifiers encoding an action choice state. The length of this array is in the field ngram_sz of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the actor. You can retrieve that length later by the function qsmm_get_actor_ngram_sz. The argument paramp is a user parameter passed to qsmm_actor_enum_ngrams.

The callback function shall return a positive value to continue the process of enumeration, zero to terminate the process of enumeration, or a negative value on error.

Use the following function to remove information on an action choice state from the memory of an actor.

Function: int qsmm_actor_remove_ngram (qsmm_actor_t actor, const qsmm_sig_t *sig_ngram_p)

This function removes information on an action choice state encoded by an array of signal identifiers sig_ngram_p from the memory of an actor. The length of this array is in the field ngram_sz of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the actor. You can retrieve that length later by the function qsmm_get_actor_ngram_sz.

For a small actor, the function removes information on the action choice state held in statistics storage with a handle retrievable by the function qsmm_get_actor_storage. For a large actor, the function removes the following pieces of information if they exist:

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_NGRAM

The array sig_ngram_p does not encode a valid action choice state. To determine the validity of an action choice state, the function checks that array for accordance with allowed ranges of signal identifiers specified by the field range_sig_p of qsmm_actor_desc_s structure when creating the actor.

QSMM_ERR_NOTFOUND

No information on the action choice state—nothing to remove.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation for a large actor. This error can leave the large actor in inconsistent state. If after removing a reason of this error a repeated call to this function succeeds, or the function reports QSMM_ERR_NOTFOUND, the actor’s state becomes consistent.


Next: , Previous: , Up: Adaptive Probabilistic Mapping   [Contents][Index]