ptolemy.domains.ci.kernel

Class CIDirector

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.actor.Director

ptolemy.domains.ci.kernel.CIDirector

All Implemented Interfaces:

java.lang.Cloneable, Executable, Initializable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class CIDirector
extends Director

Director of the component interaction (CI) domain. The CI domain supports two styles of interaction between actors, push and pull. In push interaction, the actor that produces data initiates the interaction. The receiving actor reacts to the data. The computation proceeds as data-driven. In pull interaction, the actor that consumes data decides when the interaction takes place, and the computation proceeds as demand-driven.

When a relation connects the push(pull) output port of one actor with the push(pull) input port of another, the style of interaction between the two actors is push(pull). To configure a port as a push port, add a parameter named push to the port, and give the value "true" to the parameter. Ports are pull ports by default. Relations connecting both push and pull ports are not supported. (TODO: add check in the director.)

Actors in a CI model are classified as either active or inactive. Each active actor is controlled by an actor manager, which runs asynchronously with respect to the director (i.e. not in the same thread of control). Active actors include:

• source actors with push output ports
• sink actors with pull input ports
• actors with pull input ports and push output ports

These actors initiate all the computation in a CI model. The director controls the execution of inactive actors by maintaining a task queue. A task in the queue is an inactive actor that either receives a token from an active actor via the push interaction, or is requested to produce a token by an active actor via the pull interaction. In one iteration of the CI model, the director removes the first actor from the queue. If the actor is pushed, the computation proceeds as data-driven from the actor, until the produced data reach actors that are either not ready to fire or with pull output ports and no pending pull request. If the actor is pulled, then the computation proceeds as demand-driven from the actor, until either the actor is fired or the pull request reaches actors that have push input ports and are not ready to fire.

Since:

Ptolemy II 3.0

Version:

$Id$

Author:

Xiaojun Liu, Yang Zhao

Pt.AcceptedRating:

Red (liuxj)

Pt.ProposedRating:

Yellow (liuxj)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
protected long	_interval The default interval between iterations of active actors.
protected boolean	_pauseRequested If true, pause the execution of the model.

Fields inherited from class ptolemy.actor.Director

_actorsFinishedExecution, _aspectForActor, _aspectsPresent, _defaultMicrostep, _executionAspects, _finishRequested, _initializables, _nextScheduleTime, _stopRequested, _tokenSentToCommunicationAspect, _zeroTime, localClock, startTime, stopTime

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _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

Constructors

Constructor and Description
CIDirector() Construct a director in the default workspace with an empty string as its name.
CIDirector(CompositeEntity container, java.lang.String name) Construct a director in the given container with the given name.
CIDirector(Workspace workspace) Construct a director in the workspace with an empty name.

Method Summary

Modifier and Type	Method and Description
protected void	_actorEnabled(Actor actor) Schedule the pulled inactive actor to fire.
protected void	_addActorManager(ActiveActorManager actorManager) Add the actor manager to the set of active actor managers.
protected void	_addAsyncPushedActor(Actor actor) Add the given actor to the list of actors that received pushed data from active actors.
protected void	_addSyncPushedActor(Actor actor) Add the given actor to the list of synchronously pushed actors.
protected static boolean	_isActive(Actor actor) Return true if the actor is active, such as: source with push output; sink with pull input; actor with pull input and push output.
protected boolean	_isPulled(Actor actor) Return true if the given actor has a pending pull request.
protected static boolean	_isPushPort(IOPort port) Return true if the port is a push port, that is a port having a parameter named push with boolean value true.
protected boolean	_isStopRequested() Return true if this director is requested to stop.
protected void	_removeActorManager(ActiveActorManager actorManager) Remove the actor manager from the set of active actor managers.
protected void	_requestAsyncPull(Actor actor) Handle the pull request from the given active actor.
protected void	_requestSyncPull(Actor actor) Record the given actor as being pulled, and recursively propagate the pull request to those actors providing data to it.
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
void	fire() Check whether there is an actor pushed or pulled by an active actor.
void	initialize() Initialize the model controlled by this director.
Receiver	newReceiver() Return a new receiver of type CIReceiver.
boolean	postfire() Return false if all active actors have finished execution and there is no pushed data or pull request to be processed; otherwise, return true.
boolean	prefire() If this director is at the top level of the model or there is pushed data or pull request to be processed, return true; otherwise, return false.
void	preinitialize() Validate the attributes and then invoke the preinitialize() methods of all its deeply contained actors.
void	stop() Request that the director cease execution altogether.
void	stopFire() Request that execution of the current iteration stop.
void	terminate() Terminate any currently executing model with extreme prejudice.
void	wrapup() Invoke the wrapup() method of all the actors contained in the director's container.

Methods inherited from class ptolemy.actor.Director

_actorFinished, _consultTimeRegulators, _description, _isEmbedded, _isTopLevel, _schedule, _transferInputs, _transferOutputs, addInitializable, attributeChanged, createSchedule, defaultDependency, delayDependency, elapsedTimeSinceStart, finish, fireAt, fireAt, fireAt, fireAtCurrentTime, fireContainerAt, fireContainerAt, getCausalityInterface, getCurrentTime, getDeadline, getEnvironmentTime, getExecutionAspect, getGlobalTime, getModelNextIterationTime, getModelStartTime, getModelStopTime, getModelTime, getNextIterationTime, getStartTime, getStopTime, getTimeResolution, implementsStrictActorSemantics, initialize, invalidateResolvedTypes, invalidateSchedule, isEmbedded, isFireFunctional, isStopRequested, isStrict, iterate, mutexLockObject, notifyTokenSentToCommunicationAspect, preinitialize, removeInitializable, requestInitialization, resume, resumeActor, scheduleContainedActors, setContainer, setCurrentTime, setEmbedded, setModelTime, setTimeResolution, suggestedModalModelDirectors, supportMultirateFiring, suspend, transferInputs, transferOutputs, transferOutputs

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setName, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, decorators, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, notifyOfNameChange, propagateExistence, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

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

Field Detail

_pauseRequested

protected boolean _pauseRequested

If true, pause the execution of the model.

_interval

protected long _interval

The default interval between iterations of active actors.

Constructor Detail

CIDirector

public CIDirector()
           throws IllegalActionException,
                  NameDuplicationException

Construct a director in the default workspace with an empty string as its name. The director is added to the list of objects in the workspace. Increment the version number of the workspace.

Throws:

NameDuplicationException - If construction of Time objects fails.

IllegalActionException - If construction of Time objects fails.

CIDirector

public CIDirector(Workspace workspace)
           throws IllegalActionException,
                  NameDuplicationException

Construct a director in the workspace with an empty name. The director is added to the list of objects in the workspace. Increment the version number of the workspace.

Parameters:

workspace - The workspace of this director.

Throws:

NameDuplicationException - If construction of Time objects fails.

IllegalActionException - If construction of Time objects fails.

CIDirector

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

Construct a director in the given container with the given name. The container argument must not be null, or a NullPointerException will be thrown. If the name argument is null, then the name is set to the empty string. Increment the version number of the workspace.

Parameters:

container - The container.

name - The name of this director.

Throws:

IllegalActionException - If the name has a period in it, or the director is not compatible with the specified container.

NameDuplicationException - If the container already contains an attribute with the specified name.

Method Detail

clone

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

Clone the object into the specified workspace. The new object is not added to the directory of that workspace (you must do this yourself if you want it there). The result is an object with no container.

Overrides:

clone in class Director

Parameters:

workspace - The workspace for the cloned object.

Returns:

The new object.

Throws:

java.lang.CloneNotSupportedException - Not thrown in this base class

See Also:

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

fire

public void fire()
          throws IllegalActionException

Check whether there is an actor pushed or pulled by an active actor. If there is a pushed actor, proceed with data-driven computation from the actor. For an asynchronously pulled actor, proceed with demand-driven computation from the actor.

If this director is not at the top level of the model, return after completing the data-driven computation for a pushed actor or propagating the pull request for a pulled actor; otherwise, wait until active actors produce pushed data or pull requests.

This method is not synchronized on the workspace, so the caller should be.

Specified by:

fire in interface Executable

Overrides:

fire in class Director

Throws:

IllegalActionException - If any called method of one of the associated actors throws it.

initialize

public void initialize()
                throws IllegalActionException

Initialize the model controlled by this director. For each active actor, create an instance of ActiveActorManager and start it.

This method is not synchronized on the workspace, so the caller should be.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class Director

Throws:

IllegalActionException - If the initialize() method of one of the associated actors throws it.

newReceiver

public Receiver newReceiver()

Return a new receiver of type CIReceiver.

Overrides:

newReceiver in class Director

Returns:

A new CIReceiver.

postfire

public boolean postfire()
                 throws IllegalActionException

Return false if all active actors have finished execution and there is no pushed data or pull request to be processed; otherwise, return true.

Specified by:

postfire in interface Executable

Overrides:

postfire in class Director

Returns:

True to continue execution, and false otherwise.

Throws:

IllegalActionException - Not thrown in this base class.

prefire

public boolean prefire()
                throws IllegalActionException

If this director is at the top level of the model or there is pushed data or pull request to be processed, return true; otherwise, return false.

Specified by:

prefire in interface Executable

Overrides:

prefire in class Director

Returns:

True.

Throws:

IllegalActionException - Not thrown in this base class.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Validate the attributes and then invoke the preinitialize() methods of all its deeply contained actors. This method is invoked once per execution, before any iteration, and before the initialize() method. Time is not set during this stage. So preinitialize() method of actors should not make use of time. They should wait until the initialize phase of the execution.

This method is not synchronized on the workspace, so the caller should be.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class Director

Throws:

IllegalActionException - If the preinitialize() method of one of the associated actors throws it.

stop

public void stop()

Request that the director cease execution altogether. This causes a call to stop() on all actors contained by the container of this director, and sets a flag so that the next call to postfire() returns false.

Specified by:

stop in interface Executable

Overrides:

stop in class Director

stopFire

public void stopFire()

Request that execution of the current iteration stop. Pass the request to all actors that are deeply contained by the container of this director. Notify the threads that manage active actors to stop.

Specified by:

stopFire in interface Executable

Overrides:

stopFire in class Director

terminate

public void terminate()

Terminate any currently executing model with extreme prejudice. This method is not intended to be used as a normal route of stopping execution. To normally stop execution, call the finish() method instead. This method should be called only when execution fails to terminate by normal means due to certain kinds of programming errors (infinite loops, threading errors, etc.). There is no assurance that the topology will be in a consistent state after this method returns. The topology should probably be recreated before attempting any further operations.

Calls terminate() on all actors contained by the container of this director. Set the _stopRequested flag to be true, and interrupt the actor manager threads.

Specified by:

terminate in interface Executable

Overrides:

terminate in class Director

wrapup

public void wrapup()
            throws IllegalActionException

Invoke the wrapup() method of all the actors contained in the director's container. Notify and wait for the threads that manage active actors to stop. This method is not synchronized on the workspace, so the caller should be.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class Director

Throws:

IllegalActionException - If the wrapup() method of one of the associated actors throws it.

_actorEnabled

protected void _actorEnabled(Actor actor)

Schedule the pulled inactive actor to fire.

Parameters:

actor - The pulled actor that is ready to fire.

_addActorManager

protected void _addActorManager(ActiveActorManager actorManager)

Add the actor manager to the set of active actor managers.

Parameters:

actorManager - An active actor manager.

_addAsyncPushedActor

protected void _addAsyncPushedActor(Actor actor)

Add the given actor to the list of actors that received pushed data from active actors. Notify this director.

Parameters:

actor - The actor that received pushed data from an active actor.

_addSyncPushedActor

protected void _addSyncPushedActor(Actor actor)

Add the given actor to the list of synchronously pushed actors. This is done when the actor receives pushed data from an actor executing in the director's thread.

Parameters:

actor - The actor that received synchronously pushed data.

_isActive

protected static boolean _isActive(Actor actor)
                            throws IllegalActionException

Return true if the actor is active, such as: source with push output; sink with pull input; actor with pull input and push output.

Parameters:

actor - The actor to be tested whether it is active.

Returns:

True if the actor is active.

Throws:

IllegalActionException

_isPulled

protected boolean _isPulled(Actor actor)

Return true if the given actor has a pending pull request.

Parameters:

actor - The actor to test.

Returns:

True if the given actor has been pulled.

_isPushPort

protected static boolean _isPushPort(IOPort port)

Return true if the port is a push port, that is a port having a parameter named push with boolean value true. Otherwise the port is considered a pull port.

Parameters:

port - The port to test.

Returns:

True if the port is a push port.

_isStopRequested

protected boolean _isStopRequested()

Return true if this director is requested to stop.

Returns:

True if this director is requested to stop.

_removeActorManager

protected void _removeActorManager(ActiveActorManager actorManager)

Remove the actor manager from the set of active actor managers.

Parameters:

actorManager - An active actor manager.

_requestAsyncPull

protected void _requestAsyncPull(Actor actor)

Handle the pull request from the given active actor. Add actors providing data to the given actor to the asynchronously pulled actor list. Wake up the director thread if it is waiting.

Parameters:

actor - The active actor with pull request.

_requestSyncPull

protected void _requestSyncPull(Actor actor)
                         throws IllegalActionException

Record the given actor as being pulled, and recursively propagate the pull request to those actors providing data to it.

Parameters:

actor - The actor being pulled.

Throws:

IllegalActionException - If calling prefire() on an actor in that provides data to the actor being pulled throws it