ptolemy.domains.ptera.kernel

Class Event

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.InstantiableNamedObj

ptolemy.kernel.Entity<T>

ptolemy.kernel.ComponentEntity

ptolemy.domains.modal.kernel.State

ptolemy.domains.ptera.kernel.Event

All Implemented Interfaces:

java.lang.Cloneable, Initializable, ConfigurableEntity, Changeable, Configurable, Debuggable, DebugListener, Derivable, DropTargetHandler, Flowable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

Configure, GTEvent, ListDirectory, Plot, ReceiveInput, Report, SetTableau, Sleep, Stop, Test

public class Event
extends State
implements Initializable

A Ptera event is contained by a Ptera controller in a Ptera modal model. Each event can be placed in the Ptera controller's event queue when it is scheduled. When the model time reaches the time of the scheduled event, the event is removed from the event queue and is processed. Actions can be associated with each event, so that processing an event causes those actions to be executed.

An event may schedule another event after a 0 or greater delay of model time. This scheduling relation may be guarded by a Boolean expression. When an event schedules another, processing the first one causes the second one to be placed in the same Ptera controller's event queue. An event may also cancel another event that was previously placed in the same Ptera controller's event queue but has not been processed yet.

If the fireOnInput parameter of an event is set to true, then the event is also placed in its Ptera controller's input event queue when scheduled. When the Ptera controller receives an input at any of its input ports, all the events in its input event queue are removed and processed. Those events can use the value of that input in their guards or actions.

An event may also define 0 or more formal parameters. When it is scheduled, on the scheduling relation, values to those parameters must be provided.

When an event is processed, if there are actions defined for it, then those actions are executed. This happens before the refinements of the event is fired, if any.

One or more variable names can be listed in the monitoredVariables parameter, separated by commas. If any such variable names are specified, when the model is executed, changes on those variables are captured by the event. This means, if the event is scheduled in the Ptera controller's event queue and a change is made on the variable (e.g., by the user or by actors such as SetVariable), then the event is processed even though its scheduled time has not arrive yet.

This class extends the State class in FSM, but it implements a model of computation whose semantics is completely different from FSM. Extending from FSM only because this makes it possible to reuse the user interface implemented for FSM.

Since:

Ptolemy II 8.0

Version:

$Id: Event.java 70402 2014-10-23 00:52:20Z cxh $

Author:

Thomas Huining Feng

Accepted Rating:

Red (tfeng)

Proposed Rating:

Yellow (tfeng)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Event.EventParameter The parameter to store an argument passed on a scheduling relation to this event.
static class	Event.RefiringData A data structure to store the model time advance for the refire() method to be called.

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

Entity.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
ActionsAttribute	actions The actions for this event.
Parameter	isEndingEvent A Boolean parameter that determines whether the event is the ending of a submodel, which means the outgoing scheduling relations from the event that the submodel is associated with should be evaluated.
Parameter	isFinalEvent A Boolean parameter to specify whether this event is a final event.
Parameter	isInitialEvent A Boolean parameter to specify whether this event is an initial event.
ParametersAttribute	parameters A list of formal parameters.

Fields inherited from class ptolemy.domains.modal.kernel.State

incomingPort, isFinalState, isInitialState, outgoingPort, refinementName, saveRefinementsInConfigurer

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

Constructor Summary

Constructors

Constructor and Description
Event(CompositeEntity container, java.lang.String name) Construct an event with the given name contained by the specified composite entity.

Method Summary

Modifier and Type	Method and Description
protected ParserScope	_getParserScope() Return the parser scope used to evaluate the actions and values associated with scheduling relations.
protected boolean	_isActiveRefinement(TypedActor refinement) Return whether the refinement is active.
void	addInitializable(Initializable initializable) Add the specified object to the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.
void	attributeChanged(Attribute attribute) React to a change in an attribute.
java.lang.Object	clone(Workspace workspace) Clone the event into the specified workspace.
Event.RefiringData	fire(Token arguments) Process this event with the given arguments.
PteraController	getController() Return the Ptera controller that contains this event.
void	initialize() Begin execution of the actor.
boolean	isEndingEvent() Return whether this event is an ending event.
boolean	isFinalEvent() Return whether this event is a final event, so that its execution causes the event queue of the Ptera director to be cleared.
boolean	isInitialEvent() Return whether this event is an initial event, so that it is automatically scheduled at model time 0 in the Ptera director's event queue.
void	preinitialize() This method should be invoked exactly once per execution of a model, before any of these other methods are invoked.
Event.RefiringData	refire(Token arguments, Event.RefiringData data) Continue the processing of this event with the given arguments from the previous fire() or refire().
void	removeInitializable(Initializable initializable) Remove the specified object from the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.
void	scheduleEvents() Schedule the next events by evaluating all scheduling relations from this event.
void	setContainer(CompositeEntity container) Specify the container, adding the entity to the list of entities in the container.
void	stop() Request that the event cease execution altogether.
void	wrapup() This method is invoked exactly once per execution of an application.

Methods inherited from class ptolemy.domains.modal.kernel.State

_exportMoMLContents, configure, dropObject, errorTransitionList, getConfigurer, getConfigureSource, getConfigureText, getIncomingPort, getObjectInRefinement, getOutgoingPort, getRefinement, nonErrorNonTerminationTransitionList, nonpreemptiveTransitionList, preemptiveTransitionList, terminationTransitionList

Methods inherited from class ptolemy.kernel.ComponentEntity

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

Methods inherited from class ptolemy.kernel.Entity

_addPort, _description, _removePort, _validateSettables, connectedPortList, connectedPorts, connectionsChanged, 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, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, decorators, 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, notifyOfNameChange, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, 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.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getDisplayName, getFullName, getName, getName

Field Detail

actions

public ActionsAttribute actions

The actions for this event.

isEndingEvent

public Parameter isEndingEvent

A Boolean parameter that determines whether the event is the ending of a submodel, which means the outgoing scheduling relations from the event that the submodel is associated with should be evaluated. The difference between an ending event and a final event is that the latter also clears the submodel's local event queue, whereas the former doesn't. It just triggers the outgoing scheduling relations.

isFinalEvent

public Parameter isFinalEvent

A Boolean parameter to specify whether this event is a final event.

isInitialEvent

public Parameter isInitialEvent

A Boolean parameter to specify whether this event is an initial event.

parameters

public ParametersAttribute parameters

A list of formal parameters.

Constructor Detail

Event

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

Construct an event with the given name contained by the specified composite entity. The container argument must not be null, or a NullPointerException will be thrown. This event will use the workspace of the container for synchronization and version counts. If the name argument is null, then the name is set to the empty string. Increment the version of the workspace. This constructor write-synchronizes on the workspace.

Parameters:

container - The container.

name - The name of the state.

Throws:

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

NameDuplicationException - If the name coincides with that of an entity already in the container.

Method Detail

addInitializable

public void addInitializable(Initializable initializable)

Add the specified object to the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.

Specified by:

addInitializable in interface Initializable

Parameters:

initializable - The object whose methods should be invoked.

See Also:

removeInitializable(Initializable)

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

React to a change in an attribute. If the changed attribute is the parameters attribute, update the parser scope for the actions so that the parameters' names can be referred to in those actions. If it is monitoredVariables, register this event as a value listener of all the monitored variables. If the changed attribute is isInitialState, do nothing. This is because the Ptera controller need not be updated with this attribute is set. If the changed attribute is among the other attributes, then the superclass is called.

Overrides:

attributeChanged in class State

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If thrown by the superclass attributeChanged() method, or the parser scope cannot be updated.

clone

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

Clone the event into the specified workspace. This calls the base class and then sets the attribute and port public members to refer to the attributes and ports of the new state.

Overrides:

clone in class State

Parameters:

workspace - The workspace for the new event.

Returns:

A new event.

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 Event.RefiringData fire(Token arguments)
                        throws IllegalActionException

Process this event with the given arguments. The number of arguments provided must be equal to the number of formal parameters defined for this event, and their types must match. The actions of this event are executed.

Parameters:

arguments - The arguments used to process this event, which must be either an ArrayToken or a RecordToken.

Returns:

A refiring data structure that contains a non-negative double number if refire() should be called after that amount of model time, or null if refire() need not be called.

Throws:

IllegalActionException - If the number of the arguments or their types do not match, the actions cannot be executed, or any expression (such as guards and arguments to the next events) cannot be evaluated.

See Also:

refire(Token, RefiringData)

getController

public PteraController getController()

Return the Ptera controller that contains this event.

Returns:

The Ptera controller.

initialize

public void initialize()
                throws IllegalActionException

Begin execution of the actor. This is invoked exactly once after the preinitialization phase. Since type resolution is done in the preinitialization phase, along with topology changes that may be requested by higher-order function actors, an actor can produce output data and schedule events in the initialize() method.

Specified by:

initialize in interface Initializable

Throws:

IllegalActionException - If execution is not permitted.

isEndingEvent

public boolean isEndingEvent()
                      throws IllegalActionException

Return whether this event is an ending event. When an ending event in a submodel is processed, the outgoing scheduling relations from the event that the submodel is associated with should be evaluated.

The difference between an ending event and a final event is that the latter also clears the submodel's local event queue, whereas the former doesn't. It just triggers the outgoing scheduling relations.

Returns:

true if this event is an ending event, or false otherwise.

Throws:

IllegalActionException - If the expression of the isEndingEvent parameter cannot be parsed or cannot be evaluated, or if the result of evaluation violates type constraints, or if the result of evaluation is null and there are variables that depend on this one.

isFinalEvent

public boolean isFinalEvent()
                     throws IllegalActionException

Return whether this event is a final event, so that its execution causes the event queue of the Ptera director to be cleared.

Returns:

true if this event is a final event, or false otherwise.

Throws:

IllegalActionException - If the expression of the isFinalEvent parameter cannot be parsed or cannot be evaluated, or if the result of evaluation violates type constraints, or if the result of evaluation is null and there are variables that depend on this one.

isInitialEvent

public boolean isInitialEvent()
                       throws IllegalActionException

Return whether this event is an initial event, so that it is automatically scheduled at model time 0 in the Ptera director's event queue.

Returns:

true if this event is an initial event, or false otherwise.

Throws:

IllegalActionException - If the expression of the isInitialEvent parameter cannot be parsed or cannot be evaluated, or if the result of evaluation violates type constraints, or if the result of evaluation is null and there are variables that depend on this one.

preinitialize

public void preinitialize()
                   throws IllegalActionException

This method should be invoked exactly once per execution of a model, before any of these other methods are invoked. For actors, this is invoked prior to type resolution and may trigger changes in the topology, changes in the type constraints.

Specified by:

preinitialize in interface Initializable

Throws:

IllegalActionException - If initializing is not permitted.

refire

public Event.RefiringData refire(Token arguments,
                                 Event.RefiringData data)
                          throws IllegalActionException

Continue the processing of this event with the given arguments from the previous fire() or refire(). The number of arguments provided must be equal to the number of formal parameters defined for this event, and their types must match. The actions of this event are executed.

Parameters:

arguments - The arguments used to process this event, which must be either an ArrayToken or a RecordToken.

data - The refiring data structure returned by the previous fire() or refire().

Returns:

A refiring data structure that contains a non-negative double number if refire() should be called after that amount of model time, or null if refire() need not be called.

Throws:

IllegalActionException - If the number of the arguments or their types do not match, the actions cannot be executed, or any expression (such as guards and arguments to the next events) cannot be evaluated.

See Also:

fire(Token)

removeInitializable

public void removeInitializable(Initializable initializable)

Remove the specified object from the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object. If the specified object is not on the list, do nothing.

Specified by:

removeInitializable in interface Initializable

Parameters:

initializable - The object whose methods should no longer be invoked.

See Also:

addInitializable(Initializable)

scheduleEvents

public void scheduleEvents()
                    throws IllegalActionException

Schedule the next events by evaluating all scheduling relations from this event. This method uses the argument values passed to this event by the previous invocation to fire(Token). If fire(Token) has never been called, it uses a default scope in which no argument value has been given.

This method searches for all the events that are scheduled or cancelled by this event. For each scheduling relation from this event, the guard is tested. If it is true, the ending event (which could be the same as this event) is scheduled to occur after the specified amount of delay. Arguments to that event, if any, are also computed at this time. For each cancelling edge from this event, the ending event is cancelled in the containing Ptera controller's event queue, if it is in it.

All the scheduling relations from this events are tested with their guards. If a scheduling relation's guard returns true, then the event that it points to is scheduled to occur after the amount of model time specified by the scheduling relation's delay parameter.

Throws:

IllegalActionException - If the scheduling relations cannot be evaluated.

setContainer

public void setContainer(CompositeEntity container)
                  throws IllegalActionException,
                         NameDuplicationException

Specify the container, adding the entity to the list of entities in the container. If the container already contains an entity with the same name, then throw an exception and do not make any changes. Similarly, if the container is not in the same workspace as this entity, throw an exception. If this entity is a class element and the proposed container does not match the current container, then also throw an exception. If the entity is already contained by the container, do nothing. If this entity already has a container, remove it from that container first. Otherwise, remove it from the directory of the workspace, if it is present. If the argument is null, then unlink the ports of the entity from any relations and remove it from its container. It is not added to the workspace directory, so this could result in this entity being garbage collected. Derived classes may further constrain the container to subclasses of CompositeEntity by overriding the protected method _checkContainer(). This method validates all deeply contained instances of Settable, since they may no longer be valid in the new context. This method is write-synchronized to the workspace and increments its version number.

Overrides:

setContainer in class ComponentEntity

Parameters:

container - The proposed container.

Throws:

IllegalActionException - If the action would result in a recursive containment structure, or if this entity and container are not in the same workspace, or if the protected method _checkContainer() throws it, or if a contained Settable becomes invalid and the error handler throws it.

NameDuplicationException - If the name of this entity collides with a name already in the container.

See Also:

ComponentEntity.getContainer()

stop

public void stop()

Request that the event cease execution altogether.

wrapup

public void wrapup()
            throws IllegalActionException

This method is invoked exactly once per execution of an application. None of the other action methods should be be invoked after it. It finalizes an execution, typically closing files, displaying final results, etc. When this method is called, no further execution should occur.

Specified by:

wrapup in interface Initializable

Throws:

IllegalActionException - If wrapup is not permitted.

_getParserScope

protected ParserScope _getParserScope()

Return the parser scope used to evaluate the actions and values associated with scheduling relations. The parser scope can evaluate names in the parameter list of this event. The values for those names are obtained from the given array of arguments.

Returns:

The parser scope. arguments do not match those of the defined parameters.

_isActiveRefinement

protected boolean _isActiveRefinement(TypedActor refinement)
                               throws IllegalActionException

Return whether the refinement is active. In this base class, any refinement is active, so true is returned all the time. Subclasses may override this method to ignore the automatic firing of some refinements.

Parameters:

refinement - The refinement to be tested.

Returns:

True if the refinement is active; false otherwise.

Throws:

IllegalActionException - Not thrown in this base class.