breve Documentation: version 1.9 | ||
---|---|---|
<< previous | next >> |
breve allows simulations and individual objects within simulations to be archived into human-readable XML files, and then later extracted. This chapter first describes how individual objects can be archived and dearchived (Section 9.1) and then how entire simulations can be archived and dearchived (Section 9.2).
This method of saving and loading instances can be done with any type of object. When an object is dearchived with this method, a new instance is created for the saved object. This is in contrast to the method described in Section 9.2, which loads data into the contents of existing objects.
Variables of type object
and
pointer
can not be automatically maintained without
special treatment. This is because an object
may
reference another, which in turn references several others, and so forth.
If all object
variables were maintained, then a huge
chain reaction would result every time an instance was saved.
To avoid this, saving objects does not include an object variable unless the the object being saved has declared it as a dependency, using the Object method add-dependency. If you define an object, Y, as a dependency of X, then saving X will also save Y. Loading the saved instance X will also recreate the instance Y.
Because adding dependencies also has the potential to lead to chain-reactions of archiving, it should be used with care. Generally, an object should only add dependencies on objects it has created and for which it is exclusively responsible. So while a simulated creature might legitimately add a dependency on an object containing its genome or an object which determines its movement (a "brain"), it would be inappropriate for the object to add a dependency on the controller object, or other creatures in the world.
When an object is to be archived using this technique, the user-supplied
method archive
is executed for the object. In your
archive
method, you should include code that
might be needed to prepare the object for archiving such as updating variables
which will be required when the object is dearchived. Your
archive
method must, on success, return 1. Any
other return value is considered failure
and will abort the archive.
When an object is to be dearchived using this method, the user-supplied method
dearchive
is executed for the object. In your
dearchive
method, you should include code that
might be needed to restore the state of the object, or to inform the rest of
the simulation of its presence if necessary. Your dearchive method
must, on success, return 1. Any other return value is considered
failure and will abort the archive.
Once dependencies, archive methods and dearchive methods (all of which may prove to be unnecessary for most straightforward classes) are addressed, you may initiate an archive using the Object method archive-as-xml.
To dearchive an object previously archived with this technique, use the Control method dearchive-xml. Note that this creates new instances of the objects in the archived file, instead of "filling" an existing object.
<< previous | breve Documentation table of contents | next >> |
Saving Snapshots | Saving and Loading the Entire State of a Simulation |