ptolemy.backtrack.manual.ptolemy.actor.lib
Class Backtrack

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.backtrack.manual.ptolemy.actor.lib.Backtrack

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class Backtrack
extends TypedAtomicActor

This actor provides the interface to the backtracking mechanism. It is able to create checkpoints (in which case a checkpoint handle is returned) and roll back to previously created checkpoints. This actor has a "checkpoint" input port. It takes a boolean token in every firing, which means whether a checkpoint should be created. If it is true, a checkpoint will be created in the firing, and the checkpoint handle (a long number) will be output to the "handle" output port; otherwise, no output value will be sent to the "handle" port. The "rollback" input port takes a checkpoint handle (a long number) in each firing. If the handle is greater than 0, a rollback operation will be performed, and the whole model, including its hierarchical components if any, restores its previous state recorded for that checkpoint; if the given checkpoint handle is equal to or less than 0, the rollback operation will not be performed.

Since:

Ptolemy II 6.1

Version:

$Id: Backtrack.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Thomas Feng

See Also:

Serialized Form

Accepted Rating:

Red (tfeng)

Proposed Rating:

Red (tfeng)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

private TypedIOPort	_checkpoint The input port that receives boolean tokens meaning whether checkpoints should be created.
private long	_currentHandle The last returned checkpoint handle.
private TypedIOPort	_handle The output port that sends out the newly created checkpoint handle.
private java.util.HashMap<java.lang.Long,java.util.HashMap<Checkpoint,java.lang.Long>>	_handleMap The map from checkpoint handle output by this actor to the map of checkpoint handles returned by checkpoint objects.
private TypedIOPort	_rollback The input port that receives long tokens as the checkpoint handles to roll back (if greater than 0).
private long	_rollbackHandle The checkpoint handle to roll back if greater than 0.

Fields inherited from class ptolemy.actor.AtomicActor

_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Fields inherited from interface ptolemy.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

Backtrack(CompositeEntity container, java.lang.String name)
Construct an actor in the specified container with the specified name.

Method Summary

private void	_checkpoint(java.util.HashMap<Checkpoint,java.lang.Long> handles, CompositeActor container) Create checkpoints for the actors in the given composite actor, and record the checkpoint handles in the map.
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	fire() Create checkpoint and record the given checkpoint handle if required.
boolean	postfire() Commit the rollback operation if it is required in fire().

Methods inherited from class ptolemy.actor.TypedAtomicActor

_addPort, _fireAt, _fireAt, attributeTypeChanged, clone, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, addActorFiringListener, addInitializable, connectionsChanged, createReceivers, declareDelayDependency, getCausalityInterface, getDirector, getExecutiveDirector, getManager, initialize, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, prefire, preinitialize, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, stop, stopFire, terminate, wrapup

Methods inherited from class ptolemy.kernel.ComponentEntity

_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_description, _exportMoMLContents, _removePort, _validateSettables, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ptolemy.actor.Actor

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

isFireFunctional, isStrict, iterate, prefire, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, initialize, preinitialize, removeInitializable, wrapup

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

_checkpoint

private TypedIOPort _checkpoint

The input port that receives boolean tokens meaning whether checkpoints should be created.

_currentHandle

private long _currentHandle

The last returned checkpoint handle. The next checkpoint handle to be returned will be greater by 1.

_handle

private TypedIOPort _handle

The output port that sends out the newly created checkpoint handle.

_handleMap

private java.util.HashMap<java.lang.Long,java.util.HashMap<Checkpoint,java.lang.Long>> _handleMap

The map from checkpoint handle output by this actor to the map of checkpoint handles returned by checkpoint objects. For each checkpoint created by this actor, there is a unique handle. A map is recorded as the value for this handle. The keys in the map are checkpoint objects managing the actors in the model; the values in the map are the checkpoint handles returned by those checkpoint objects.

_rollback

private TypedIOPort _rollback

The input port that receives long tokens as the checkpoint handles to roll back (if greater than 0).

_rollbackHandle

private long _rollbackHandle

The checkpoint handle to roll back if greater than 0. The fire method records this field. The postfire method performs the rollback if this field is greater then 0.

Constructor Detail

Backtrack

public Backtrack(CompositeEntity container,
                 java.lang.String name)
          throws IllegalActionException,
                 NameDuplicationException

Construct an actor in the specified container with the specified name. The name must be unique within the container or an exception is thrown. The container argument must not be null, or a NullPointerException will be thrown.

Parameters:

container - The container.

name - The name.

Throws:

IllegalActionException - If the actor cannot be contained by the proposed container.

NameDuplicationException - If the name coincides with an actor already in the container.

Method Detail

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the actor into the specified workspace.

Overrides:

clone in class AtomicActor

Parameters:

workspace - The workspace for the new object.

Returns:

A new actor.

Throws:

java.lang.CloneNotSupportedException - If a derived class contains an attribute that cannot be cloned.

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

fire

public void fire()
          throws IllegalActionException

Create checkpoint and record the given checkpoint handle if required. A boolean token is read from the "checkpoint" port. If the token is true, a checkpoint is created, and the checkpoint handle is sent to the "handle" output port; if the token is false, no output is sent. A long token is read from the "rollback" port. If rollback is requested, the received token contains the checkpoint handle to be rolled back to, which is greater than 0. This checkpoint handle is recorded in a private field, and the rollback operation will actually be performed in postfire().

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - If the fire method of the superclass throws this exception.

postfire

public boolean postfire()
                 throws IllegalActionException

Commit the rollback operation if it is required in fire(). If the last token received from the "rollback" port is greater than 0, it is recorded as the checkpoint handle used for the rollback. When performed, the rollback operation restores the state of the whole model.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

True if execution can continue into the next iteration.

Throws:

IllegalActionException - If the postfire method of the superclass throws this exception.

_checkpoint

private void _checkpoint(java.util.HashMap<Checkpoint,java.lang.Long> handles,
                         CompositeActor container)

Create checkpoints for the actors in the given composite actor, and record the checkpoint handles in the map. The checkpoint objects are the keys in the map, and their checkpoint handles are the values associated with the keys. Only the actors that implements the Rollbackable interface can be checkpointed. This method recursively invokes itself on the composite actors in the given composite actor.

Parameters:

handles - The map that associates the checkpoint objects with the checkpoint handles for them.

container - The composite actor to be checkpointed.