Package ptolemy.actor

Class LocalClock

  • All Implemented Interfaces:
    java.lang.Cloneable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable, Settable
    public class LocalClock
extends AbstractSettableAttribute
    A clock that keeps track of model time at a level of the model hierarchy and relates it to the time of the enclosing model, if there is one. The time of the enclosing model is referred to as the environment time. This clock has a notion of local time and committed time. The committed time is "simultaneous" with the environment time.

    The local time is not allowed to move backwards past the committed time, but ahead of that time, it can move around at will.

    There is no way of explicitly committing time, but several methods have the side effect of committing the current local time. For example, setClockDrift(double) will commit the current local time and change the clock drift. So will start() and stop()

    This class implements the AbstractSettableAttribute interface because we want the localClock to be shown as a parameter in the editor dialogue of a director. A better implementation would be to derive LocalClock from Attribute and make changes to vergil such that Attributes are displayed in the dialogue, however, for the moment, the required changes are too complex. The value of the clock is exposed as an attribute that, by default, is non editable. The clock drift is a contained attribute that can be modified.

    This class also specifies a globalTimeResolution parameter. This is a double with default 1E-10, which is 10-10. All time values are rounded to the nearest multiple of this value. If the value is changed during a run, an exception is thrown. This is a shared parameter, which means that all instances of Director in the model will have the same value for this parameter. Changing one of them changes all of them.

    FIXME: Setting of clock drift must be controlled because it commits time.

    Since:
    Ptolemy II 10.0
    Version:
    $Id$
    Author:
    Ilge Akkaya, Patricia Derler, Edward A. Lee, Christos Stergiou, Michael Zimmer
    Pt.AcceptedRating:
    red (eal)
    Pt.ProposedRating:
    yellow (eal)

    • Field Detail

      • globalTimeResolution

        public SharedParameter globalTimeResolution
        The time precision used by this director. All time values are rounded to the nearest multiple of this number. This is a double that defaults to "1E-10" which is 10-10. This is a shared parameter, meaning that changing one instance in a model results in all instances being changed.

      • clockDrift

        public Parameter clockDrift
        The drift of the local clock with respect to the environment clock. If this is a top level director the clock drift has no consequence. The value is a double that is initialized to 1.0 which means that the local clock drift matches the one of the environment.

    • Constructor Detail

      • LocalClock

        public LocalClock​(NamedObj container,
                  java.lang.String name)
           throws IllegalActionException,
                  NameDuplicationException
        Construct an attribute with the given name contained by the specified entity. The container argument must not be null, or a NullPointerException will be thrown. This attribute 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.
        Parameters:
        container - The container.
        name - The name of this attribute.
        Throws:
        IllegalActionException - If the attribute is not of an acceptable class for the container, or if the name contains a period.
        NameDuplicationException - If the name coincides with an attribute already in the container.

    • Method Detail

      • addValueListener

        public void addValueListener​(ValueListener listener)
        This method has to be implemented for the AbstractSettableAttribute interface. This interface is only needed for the LocalClock to show up in the configuration dialogue of the container (the director). The method will not be used for this class so the implementation is empty.
        Parameters:
        listener - The listener to be added.
        See Also:
        removeValueListener(ValueListener)

      • getClockDrift

        public double getClockDrift()
        Get clock drift.
        Returns:
        The clock drift.
        See Also:
        setClockDrift(double)

      • getEnvironmentTimeForLocalTime

        public Time getEnvironmentTimeForLocalTime​(Time time)
                                    throws IllegalActionException
        Get the environment time that corresponds to the given local time. The given local time is required to be either equal to or greater than the committed time when this method is called.
        Parameters:
        time - The local Time.
        Returns:
        The corresponding environment Time.
        Throws:
        IllegalActionException - If the specified local time is in the past, or if Time objects cannot be created.

      • getExpression

        public java.lang.String getExpression()
        Return the local time.
        Returns:
        The local time as a string value.
        See Also:
        Settable.setExpression(String)

      • getLocalTime

        public Time getLocalTime()
        Get current local time. If it has never been set, then this will return Time.NEGATIVE_INFINITY. The returned value may have been set by setLocalTime(Time).
        Returns:
        The current local time.
        See Also:
        setLocalTime(Time)

      • getLocalTimeForCurrentEnvironmentTime

        public Time getLocalTimeForCurrentEnvironmentTime()
                                           throws IllegalActionException
        Get the local time that corresponds to the current environment time. The current environment time is required to be greater than or equal to the environment time corresponding to the last committed local time.
        Returns:
        The corresponding local time.
        Throws:
        IllegalActionException - If Time objects cannot be created, or if the current environment time is less than the time corresponding to the last committed local time.

      • getLocalTimeForEnvironmentTime

        public Time getLocalTimeForEnvironmentTime​(Time time)
                                    throws IllegalActionException
        Get the local time that corresponds to the given environment time. The given environment time is required to be greater than or equal to the environment time corresponding to the last committed local time.
        Parameters:
        time - The environment time.
        Returns:
        The corresponding local time.
        Throws:
        IllegalActionException - If the specified environment time is less than the environment time corresponding to the last committed local time, or if Time objects cannot be created.

      • getTimeResolution

        public final double getTimeResolution()
        Get the time resolution of the model. The time resolution is the value of the timeResolution parameter. This is the smallest time unit for the model.
        Returns:
        The time resolution of the model.
        See Also:
        setTimeResolution(double)

      • initialize

        public void initialize()
        Initialize parameters that cannot be initialized in the constructor. For instance, Time objects cannot be created in the constructor because the time resolution might not be known yet. Older models have the timeResolution parameter specified in the director which will only be loaded by the MOMLParser after the director is initialized.

      • removeValueListener

        public void removeValueListener​(ValueListener listener)
        This method has to be implemented for the AbstractSettableAttribute interface. This interface is only needed for the LocalClock to show up in the configuration dialogue of the container (the director). The method will not be used for this class so the implementation is empty.
        Parameters:
        listener - The listener to be removed.
        See Also:
        addValueListener(ValueListener)

      • resetLocalTime

        public void resetLocalTime​(Time time)
        Set local time and commit. This is allowed to set time earlier than the last committed local time.
        Parameters:
        time - The new local time.

      • setLocalTime

        public void setLocalTime​(Time time)
                  throws IllegalActionException
        Set local time without committing. This is not allowed to set time earlier than the last committed local time.
        Parameters:
        time - The new local time.
        Throws:
        IllegalActionException - If the specified time is earlier than the current time.
        See Also:
        getLocalTime()

      • setTimeResolution

        public void setTimeResolution​(double timeResolution)
        Set time resolution.
        Parameters:
        timeResolution - The new time resolution.
        See Also:
        getTimeResolution()

      • setVisibility

        public void setVisibility​(Settable.Visibility visibility)
        This method has to be implemented for the AbstractSettableAttribute interface. This interface is only needed for the LocalClock to show up in the configuration dialogue of the container (the director). This method does not do anything because visibility is always NOT_EDITABLE.
        Parameters:
        visibility - The new visibility.
        See Also:
        getVisibility()

      • start

        public void start()
        Start the clock with the current drift as specified by the last call to setClockDrift(double). If setClockDrift(double) has never been called, then the drift is 1.0. This method commits current local time.

      • stop

        public void stop()
        Stop the clock. The current time will remain the same as its current value until the next call to start(). This method commits current local time.

      • validate

        public java.util.Collection validate()
                              throws IllegalActionException
        This method has to be implemented for the AbstractSettableAttribute interface. This interface is only needed for the LocalClock to show up in the configuration dialogue of the container (the director). The value of the LocalClock does not need validation, thus this method does not do anything.
        Returns:
        Null.
        Throws:
        IllegalActionException - Not thrown in this base class.