|
Moving to a state means "make the model data structure the same as it was when the state was noted." To move to any state, call
api_change_to_state with the desired state as an argument. To move to modeler state
1, you can call
api_change_state with
delta state 1 as an argument.
api_change_state is a read/write function that changes the model; it does not create bulletins or a bulletin board because they already exist in the delta state.
|
|
|
|
|
Figure 7-6. Rolling to Delta States
|
|
|
In a nonlinear or branching case, a delta state can have an additional
partner delta state pointer. The partner pointer is part of circular linked list of states branching from the same state. The partner pointer is always set; if there is no other branch, the pointer points to itself.
|
|
|
The only way to reliably get backward or forward to a given state is to give it a name and remember that name, or to remember its pointer. This is then used as the argument in the roll function.
|
|
|
Rolling the model backward presents no problems or additional overhead to the application developer. However, because branching is permitted in the delta states, roll forward could present an ambiguous situation. How does
ACIS know which state is referenced when a roll forward is requested? It doesn't. If the state is important, either the pointer or the name of a given state has to be remembered (e.g.,
api_note_state).
|
|
|
The
delete_if_empty argument in
api_note_state allows the caller to remove a delta state that contains no bulletins. So if this argument is set
TRUE, some code may need to be modified to account for deleted empty states, for example, code that relies on a particular number of states on a stream.
|
|
|
Use the partner delta state pointer to branch to the various delta states. The partner list is a circular linked list of delta states all having the same previous state. Traversing into the various branch delta states uses this circular partner list, not just the next delta state pointer. When a branch of the history is pruned, the partner delta state pointers are also updated.
|
|
|
When experimenting with roll backward
S-steps and roll forward
S+n-steps with a state having branches, you may experience unwanted side effects. Specifically, there may be a difference between what happens when rolling backward
to a branch state and then "blindly rolling forward," and what happens when rolling backward
past the branch state and then blindly rolling forward. It is the "blindly rolling forward" and the ambiguities in the branch state which have the potential for difficulties. The solution is to
not blindly roll forward, but rather to note the delta states of importance beforehand and then to explicitly roll to those states.
|
|
|
Integer identifiers, unique to a given history stream, can be requested for each entity. These IDs remain constant through roll, save and restore (with APIs
api_save_history and
api_restore_history). An entity can be returned from a given ID when the entity is alive in the active state of the history stream.
NULL is returned when the entity is not alive. This requires two SAT files changes: an extra integer in each entity and the number of tags assigned in the history stream.
|
|
|
The format of
ENTITY and
HISTORY_STREAM records accommodates the addition of entity IDs. An integer field in the entity record holds the entity's ID. A value of -1 indicates that an ID has not yet been requested for the
ENTITY. This is field #2 in any entity record, where the entity type is field #0. An integer field in history stream records (part of the history data section) holds the next available entity ID in that stream. This is field #3 in the history stream record, where "history_stream" is the first field.
|