Package ptolemy.domains.ptera.kernel

Class 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$
    Author:
    Thomas Huining Feng
    Pt.AcceptedRating:
    Red (tfeng)
    Pt.ProposedRating:
    Yellow (tfeng)

    • Field Detail

      • 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.

    • 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.