---

2.10 Revising Action Choice States ¶

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

Function: int qsmm_actor_enum_ngrams_v2 (qsmm_actor_t actor, int ngram_lower_sz, int ngram_upper_sz, int range_sz, int rez1, const qsmm_sig_t *sig_ngram_lower_p, const qsmm_sig_t *sig_ngram_upper_p, const struct qsmm_pair_sig_s *range_sig_p, qsmm_enum_ngram_callback_func_t callback_func, void *paramp) ¶

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

• action choice states with assigned references to output signal choice trees but without model nodes yet created to store tree instances;
• action choice states with model nodes already created to store instances of output signal choice trees;
• action choice states that have the pieces of information held in statistics storage with a handle retrievable by qsmm_get_actor_storage for the large actor.

If ngram_lower_sz is positive, it specifies the length of sig_ngram_lower_p array containing a lower bound for the enumerated lists—their prefixes with length ngram_lower_sz must be greater than or equal to the lower bound. If ngram_upper_sz is positive, it specifies the length of sig_ngram_upper_p array containing an upper bound for the enumerated lists—their prefixes with length ngram_upper_sz must be less than the upper bound. If range_sz is positive, it specifies the length of range_sig_p array containing allowed ranges of signal identifiers in prefixes with length range_sz in the enumerated lists—every signal identifier in a prefix must be greater than or equal to the field first of an element of range_sig_p at the same index and must be less than or equal to the field second of the element.

The function qsmm_actor_enum_ngrams_v2 compares two lists of signal identifiers from left to right. If a signal identifier in the first list is less than or greater than a signal identifier in the second list at the same index, the first list is less than or greater than the second list respectively. If the first list is a prefix of the second list, the first list is less than the second list. If the second list is a prefix of the first list, the first list is greater than the second list. If the two lists have the same length and content, the lists are equal.

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

The function qsmm_actor_enum_ngrams_v2 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

One of the following conditions is true:

• ngram_lower_sz is negative;
• ngram_lower_sz is greater than the length of a list of signal identifiers encoding an action choice state;
• ngram_lower_sz is positive, but sig_ngram_lower_p is NULL;
• ngram_upper_sz is negative;
• ngram_upper_sz is greater than the length of a list of signal identifiers encoding an action choice state;
• ngram_upper_sz is positive, but sig_ngram_upper_p is NULL;
• range_sz is negative;
• range_sz is greater than the length of a list of signal identifiers encoding an action choice state;
• range_sz is positive, but range_sig_p is NULL;
• field first in an element of range_sig_p is greater than the field second of the element;
• field second in an element of range_sig_p is greater than QSMM_SIG_MAX.

QSMM_ERR_CALLBACK

The callback function reported an error.

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_v2 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 enumerated action choice state. The field ngram_sz of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the actor specifies the length of the array. The function qsmm_get_actor_ngram_sz returns that length for a created actor. The argument paramp is a user parameter passed to qsmm_actor_enum_ngrams_v2.

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 field ngram_sz of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the actor specifies the length of the array. The function qsmm_get_actor_ngram_sz returns that length for a created actor.

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:

• reference to an output signal choice tree assigned to the action choice state;
• model node holding an instance of an output signal choice tree assigned to the action choice state;
• information on the action choice state held in statistics storage with a handle retrievable by the function qsmm_get_actor_storage for the large 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_NGRAM

The array sig_ngram_p is not a valid array of signal identifiers encoding an action choice state. To determine array validity, the function checks it 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.