|
|
Partitions and Rollback |
| <<< Simplifying Models | Chapters | Archives >>> |
Partitions are provided to help the application organize entities in the modeling session into sets of related parts, and to save these parts as a single item.
Rollback enables the application to return the Parasolid session to an earlier state. It can be applied to individual partitions, or to the whole session.
The objects used by partitions and rollback are:
A partition is a self-contained collection of bodies, orphan geometry and transforms. It can be rolled back and forward independently of other partitions.
All entities in the session are in some partition, except for:
These objects exist at a session level; they take no account of the current partition when created and are exempt from the no inter-partition references rule (see "Inter-partition references" below). They are not affected by partitioned rollback.
At any particular time, one partition is designated the current partition:
In general, inter-partition references are not allowed. This condition is imposed to avoid inconsistencies which could arise when using partitioned rollback. Therefore, many modeling operations which would create such references are not allowed; for example, uniting bodies in different partitions, attaching geometry to bodies in different partitions or intersecting surfaces in different partitions.
The behavior of PK functions is determined by the fact that if an entity is created which is referenced by an existing entity, then it must be created in the same partition as that entity. If it is not so referenced - for example a new line created by PK_LINE_create - then its partition is not so determined, and it is put in the current partition.
Therefore, if a PK function creates (or may create) a reference between two existing entities, then it may only be called if those two entities are in the same partition; for example, boolean operations may only be performed on faces and bodies in the same partition.
However, some functions are allowed to reference entities in other partitions during an operation, as long as there are no inter-partition references created when the operation has completed.
PK functions can be divided into the following groups when considering inter-partition references:
Normally entities cannot be moved between partitions, so to perform operations on them, one of the entities must be copied into the partition of the other:
However, PK_BODY_change_partition can be used to move a body into a different partition, preserving all its tags, provided that it is a new body - i.e. the body, and all entities within it, have been created since the last roll operation (create or goto) in its partition. The tags of the body and entities within it are unchanged. This can be used, for example, when receiving a transmit file with a number of bodies in it, and then distributing them to other partitions.
When an application has no further use for a partition, it should call PK_PMARK_goto to roll it to its pmark. Once a partition has been rolled to its initial pmark, it is inactive, it cannot be made current, and so entities cannot be created in it.
Partitions cannot be deleted in the normal way, as there may be pmarks in the partition created by session marks which are still accessible. Rolling to the session mark would make one of those pmarks current and reactivate the partition. The normal mark management provided by the application Frustrum should eventually remove all the pmarks in the partition except the initial one, at which point Parasolid deletes it.
See also the "Mark management - an example strategy" section at the end of this chapter.
The following functions are also relevant to partitions:
| Functions | Description |
|---|---|
Rollback is used to undo changes made since a given point, indicated by a rollmark set at that point, either by the application or the user.
There are two types of rollback:
Partitioned Rollback enables feature modeling applications to perform model update more efficiently after model parameters are changed. It is possible to roll back a model to the point where a feature was added, reapply the modified feature, and then reapply subsequent features to generate the updated model. Individual bodies or collections of bodies can be rolled back independently, so updating one model in a session does not affect other models. Branching rollback of bodies - several alternative updates to a given body - can also be implemented.
Applications still have the ability to roll the entire session back and forward - a session undo which can be invoked by the user.
The application is expected to manage the storage and purging of session and partition marks, according to its own priorities and disk management strategy. However, Parasolid does provide some assistance with mark management, such as the clean-up of pmarks done when the rollforward option is off.
Partitioned rollback cannot be switched off once selected - this is only done by stopping the Parasolid session.
The following SESSION functions are provided to help manage rollback:
| Functions | Description |
|---|---|
|
returns true if partitioned rollback was initialized by calling PK_DELTA_register_callbacks before calling PK_SESSION_start |
|
|
returns the most recent session mark, and whether the session is still at that mark (supersedes PK_MARK_ask_state) |
|
In order to roll partitions back and forth, marks are created in partitions. These are called partition marks, and the corresponding PK object is the PMARK. A partition mark can be thought of as recording a particular state of a partition.
At any time a partition has a current pmark. This is the pmark most recently created or rolled to. If the partition has not been modified (by creating, modifying, or deleting entities, or by a roll operation) since that pmark was made current, the partition is at that pmark.
Each partition has an initial pmark, and it cannot be deleted; it is the unique pmark in the partition with no preceding pmark. A newly created partition has only an initial pmark, which is current. However, the partition is not at its initial pmark, as that would represent an inactive state of the partition - a partition which is rolled back to its initial pmark is inactive, and can no longer be used.
The pmarks of a partition together form its pmark graph. Parasolid maintains the pmark graph of each partition, and the application can enquire on the sequence of pmarks contained in it:
Figure 41-2 The pmark graphs of two partitions
Figure 41-2 shows the pmark graphs of two partitions. The current pmark is shown in each case. In the case of Partition1:
At any time, both partitions can be rolled back or forward to any pmark, further modeling can be performed, or a new pmark can be created.
PK_PMARK_goto is used to roll a partition to a specified pmark. As a result of the roll operation, entities are created, modified and deleted. These are returned as arrays:
del
array were alive before the roll operation, but are dead after it
new
array
mod
array exist both before and after the roll, and may have been modified by the roll operationThe bulletin board must be emptied before PK_PMARK_goto is called, if it is switched on. The bulletin board logs operations which occur on entities in different partitions, and a partition roll could invalidate its contents (for example, if a body is used in a logged operation, then its partition is rolled back to before the body's creation).
To make a partition inactive, it must be rolled to its initial pmark. This cannot be done to the current partition.
PK_PMARK_delete is used to delete partition marks. More than one pmark can be deleted with a single call. However, the following pmarks cannot be deleted:
PK_PMARK_delete returns the pmarks which could not be deleted for these reasons.
Deleting a pmark may result in extra disk space being (temporarily) required, if the Frustrum data for a partition mark is written out again to merge the the changes (deltas) on either side of the pmark. For example, in Figure 41-2, if pmark 5 in partition 1 were deleted, n5 and n6 would be merged, keeping the pmark graph connected.
The following functions are also relevant to partition marks:
The partition rolling mechanism works by storing DELTAs (changes) between pmarks. These are byte-streams (e.g. files) which record the entities which need to be created, modified or deleted in order to move from one pmark to an adjacent one. These deltas are written out through the Frustrum interface, stored by the application Frustrum, and read back in during a roll operation.
If a new pmark is created, and the partition is currently at a pmark, a zero-length delta is written to the Frustrum.
| Functions | Description |
|---|---|
This function must be called before the Parasolid session is started, if partitioned rollback is to be used during a session. It registers the rollback Frustrum functions which the partitioned rollback system uses to read and write delta files.
See Appendix C, "PK_DELTA Functions" in the Parasolid Downward Interfaces manual.
Session rollback provides the ability to change the state of the whole session at once. It coordinates the partitions in a session by setting simultaneous pmarks in each one.
Session marks record stages in the state of the entire session, and the session can be returned to any of these marks. The PK object representing a session mark is the MARK. After the session is rolled back or forward to a session mark, the entities in the session are exactly as they were when the session mark was created (except for attribute definitions and certain session parameters which are not affected by rollback):
PK_MARK_create generates a session mark. The session mark notes the state of all partitions in the session, by creating new partition marks in all partitions which are not already at a pmark. It also notes the state of the bulletin board and session and modeling parameters, which are not in any partition.
Session marks form a linear sequence, not a branching tree. When a session mark is created, any session marks following the previously current one are first deleted.
PK_MARK_goto returns the session (i.e. all the partitions, the bulletin board, modeling parameters and some session parameters - but not attribute definitions) to its state when the given session mark was created. The current partition is set to the partition which was current when the mark was created.
If the session rollforward option is off, then when a session mark is rolled to, all session marks following it are deleted, along with all pmarks which were created after it was created.
The bulletin board and modeling parameters are rolled back by session rollback, but are unaffected by partitioned rollback. The bulletin board does not need to be empty before a session rollback operation (as it does for a partition roll operation), as it is updated by session rollback.
The following session parameters are not affected by session rollback:
All other session parameters are rolled back by a session roll operation. None are changed by partitioned rollback.
Attribute definitions are not affected - once created, they always exist during a modeling session.
PK_MARK_delete deletes a session mark. Earlier and later session marks (if any) are still accessible.
Pmarks which were created as a result of this mark being set are not deleted. These might eventually be deleted by the application as part of its mark management strategy (see "Mark management - an example strategy", at the end of this chapter, for a suggested method).
If the session is rolled back to a mark which was created before a particular partition was created, the fate of the partition depends on the setting of the roll forward session parameter:
roll_forward
is true, then the partition still exists, and is at its initial pmark (i.e. it is inactive - it cannot be made current, has no entities in it, and none can be created). Partition roll operations on it are still allowed.
roll_forward
is false, then the partition (with all its pmarks) is deleted.Note that the current partition may not be the same after session rollback, as the value of the current partition rolls with the session.
The following functions are also relevant to session marks:
| Functions | Description |
|---|---|
|
returns true if the given pmark is is used by a session mark |
|
|
returns the most recent session mark, and whether the session is still at that mark |
If the application is going to use partitioned rollback, the registered Frustrum must conform to a new interface, as follows.
Rollback files are referred to as deltas. A positive integer value for each one must be allocated by the application Frustrum. When Parasolid asks the Frustrum to create a delta, it gives it the succeeding pmark to which the delta relates.
A delta holds the changes required to get from one pmark to an adjacent one. Deltas are unidirectional, i.e. they only hold enough information to get from pmark A to pmark B, not back again. When Parasolid executes a roll operation from one pmark to an adjacent one, it creates a new reversed delta to generate the reverse route. If there is insufficient disk space to do this, the roll operation does not take place.
Similarly, if a pmark is deleted, two deltas need to be merged into one. In this case the merged delta is written out first, before deleting the original deltas.
The pmark passed to the
open_for_write
function may sometimes be PK_PMARK_null (i.e. 0), in which case the delta does not correspond to a pmark visible to the application. The application should store this delta as usual, but need not (and cannot) delete it. These pmarks are generated by internal kernel processing, and is deleted by Parasolid when no longer required.
These rollback functions must be provided as part of the application Frustrum.
|
Note: The function names used below are purely nominal, as the actual names are passed to PK_DELTA_register_callbacks. |
| Functions | Description |
|---|---|
|
opens (creates) a delta file for output, associated with the given pmark |
|
|
writes (appends) n_bytes bytes from the given array to the given delta |
|
See also Appendix C, "PK_DELTA Functions" in the Parasolid Downward Interfaces manual.
In the following sections, 'disk space' refers to wherever the application's Frustrum stores the deltas.
A session roll operation may involve writing to disk, and may require more memory, and so it is possible for the operation to fail. However, the following can be guaranteed:
The application is expected to delete partition marks and session marks as required to conserve disk space when the marks are no longer required:
If memory is exhausted or the Frustrum returns a write error during a call to PK_PARTITION_make_pmark or PK_MARK_create, the session is unchanged (apart possibly from some new pmarks having been created), so the application can free some disk and retry the call.
If memory is exhausted or the Frustrum returns a write error during a call to PK_PMARK_goto or PK_MARK_goto, then the session may have changed in that some partitions may have been rolled some or all the way to their destination pmarks. However, the application can free some disk space and retry the operation, because the session is in a known state (all partitions are at some pmark), even though it is not necessarily either the starting or the desired destination state. Note that, in the case of PK_PMARK_goto, the application should first return to the original pmark before retrying the roll operation, otherwise the returned arrays of new, modified and deleted entities are not as expected.
If the Frustrum returns a read error after successfully opening a delta file, this may in some circumstances result in a fatal error so that the Parasolid session cannot be continued.
If a run-time error occurs during a roll operation, this results in the usual failure code being returned to the PK. As with any other run-time error, the application is expected to roll back to the current session mark to recover the session to a valid state. However, a run-time error during a call to PK_MARK_goto or PK_PMARK_goto may result in a fatal error return.
If a roll operation (including PK_MARK_goto) is interrupted as a result of a call to KABORT with code user-interrupt, the usual failure code is returned to the PK, and the application should roll back to the current session mark to recover, as usual.
The following is an example of how mark management might be performed by a feature modeling application, using pmarks to record feature attachment and session marks for user-level undo.
The application makes the following assumptions for its algorithm:
Hence when a session mark is deleted, any pmarks which are not on the main line and which do not have future pmarks which are used by some session mark, can be deleted. This applies whether the session mark is explicitly deleted, or deleted as a result of a session rollback with roll-forward option off.
The remaining question is which pmarks or session marks to delete when disk becomes full or nearly full:
For partition deletion, the desired effect can be achieved by rolling the partition to its initial pmark to deactivate it. Eventually mark management deletes all the pmarks in the partition except the initial one. When it is no longer used by any session marks, Parasolid deletes it.
| <<< Simplifying Models | Chapters | Archives >>> |