Package ptolemy.cg.lib

Class ModularCompiledSDFTypedCompositeActor

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Configurable, Debuggable, DebugListener, Derivable, Instantiable, LazyComposite, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class ModularCompiledSDFTypedCompositeActor
extends ModularCodeGenLazyTypedCompositeActor
    An aggregation of typed actors with lazy evaluation. The contents of this actor can be created in the usual way via visual editor by dragging in other actors and ports and connecting them. When it exports a MoML description of itself, it describes its ports and parameters in the usual way, but contained actors, relations, and their interconnections are exported within <configure> </configure> tags. When reloading the MoML description, evaluation of the MoML within the configure tags is deferred until there is an explicit request for the contents. This behavior is useful for large complicated models where the time it takes to instantiate the entire model is large. It permits opening and browsing the model without a long wait. However, the cost comes typically when running the model. The instantiation time will be added to the time it takes to preinitialize the model.

    The lazy contents of this composite are specified via the configure() method, which is called by the MoML parser and passed MoML code. The MoML is evaluated lazily; i.e. it is not actually evaluated until there is a request for its contents, via a call to getEntity(), numEntities(), entityList(), relationList(), or any related method. You can also force evaluation of the MoML by calling populate(). Accessing the attributes or ports of this composite does not trigger a populate() call, so a visual editor can interact with the actor from the outside in the usual way, enabling connections to its ports, editing of its parameters, and rendering of its custom icon, if any.

    The configure method can be passed a URL or MoML text or both. If it is given MoML text, that text will normally be wrapped in a processing instruction, as follows: 

    <?moml
<group>
... MoML elements giving library contents ...
</group>
?>
    The processing instruction, which is enclosed in "<?" and "?>" prevents premature evaluation of the MoML. The processing instruction has a target, "moml", which specifies that it contains MoML code. The keyword "moml" in the processing instruction must be exactly as above, or the entire processing instruction will be ignored. The populate() method strips off the processing instruction and evaluates the MoML elements. The group element allows the library contents to be given as a set of elements (the MoML parser requires that there always be a single top-level element, which in this case will be the group element).

    One subtlety in using this class arises because of a problem typical of lazy evaluation. A number of exceptions may be thrown because of errors in the MoML code when the MoML code is evaluated. However, since that code is evaluated lazily, it is evaluated in a context where these exceptions are not expected. There is no completely clean solution to this problem; our solution is to translate all exceptions to runtime exceptions in the populate() method. This method, therefore, violates the condition for using runtime exceptions in that the condition that causes these exceptions to be thrown is not a testable precondition.

    A second subtlety involves cloning. When this class is cloned, if the configure MoML text has not yet been evaluated, then the clone is created with the same (unevaluated) MoML text, rather than being populated with the contents specified by that text. If the object is cloned after being populated, the clone will also be populated. Cloning is used in actor-oriented classes to create subclasses or instances of a class. When a LazyTypedCompositeActor contained by a subclass or an instance is populated, it delegates to the instance in the class definition. When that instance is populated, all of the derived instances in subclasses and instances of the class will also be populated as a side effect.

    A third subtlety is that parameters of this actor cannot refer to contained entities or relations, nor to attributes contained by those. This is a rather esoteric use of expressions, so this limitation may not be onerous. You probably didn't know you could do that anyway. An attempt to make such references will simply result in the expression failing to evaluate.

    Since:
    Ptolemy II 10.0
    Version:
    $Id$
    Author:
    Dai Bui
    Pt.AcceptedRating:
    Red (rodiers)
    Pt.ProposedRating:
    Red (rodiers)

    • Constructor Detail

      • ModularCompiledSDFTypedCompositeActor

        public ModularCompiledSDFTypedCompositeActor()
                                      throws IllegalActionException,
                                             NameDuplicationException
        Construct a library in the default workspace with no container and an empty string as its name. Add the library to the workspace directory. Increment the version number of the workspace.
        Throws:
        IllegalActionException - If the entity cannot be contained by the proposed container.
        NameDuplicationException - If the container already has an actor with this name.

      • ModularCompiledSDFTypedCompositeActor

        public ModularCompiledSDFTypedCompositeActor​(Workspace workspace)
                                      throws IllegalActionException,
                                             NameDuplicationException
        Construct a library in the specified workspace with no container and an empty string as a name. You can then change the name with setName(). If the workspace argument is null, then use the default workspace. Add the actor to the workspace directory. Increment the version number of the workspace.
        Parameters:
        workspace - The workspace that will list the actor.
        Throws:
        IllegalActionException - If the entity cannot be contained by the proposed container.
        NameDuplicationException - If the container already has an actor with this name.

    • Method Detail

      • attributeChanged

        public void attributeChanged​(Attribute attribute)
                      throws IllegalActionException
        React to a change in an attribute. This method is called by a contained attribute when its value changes. This overrides the base class so that if the attribute is an instance of TypeAttribute, then it sets the type of the port.
        Overrides:
        attributeChanged in class TypedCompositeActor
        Parameters:
        attribute - The attribute that changed.
        Throws:
        IllegalActionException - If the change is not acceptable to this container.

      • portList

        public java.util.List portList()
        Get the ports belonging to this entity. The order is the order in which they became contained by this entity. This method is read-synchronized on the workspace.
        Overrides:
        portList in class Entity
        Returns:
        An unmodifiable list of Port objects.

      • fire

        public void fire()
          throws IllegalActionException
        If this actor is opaque, transfer any data from the input ports of this composite to the ports connected on the inside, and then invoke the fire() method of its local director. The transfer is accomplished by calling the transferInputs() method of the local director (the exact behavior of which depends on the domain). If the actor is not opaque, throw an exception. This method is read-synchronized on the workspace, so the fire() method of the director need not be (assuming it is only called from here). After the fire() method of the director returns, send any output data created by calling the local director's transferOutputs method.
        Specified by:
        fire in interface Executable
        Overrides:
        fire in class CompositeActor
        Throws:
        IllegalActionException - If there is no director, or if the director's fire() method throws it, or if the actor is not opaque.

      • initialize

        public void initialize()
                throws IllegalActionException
        Create receivers and invoke the preinitialize() method of the local director. If this actor is not opaque, throw an exception. This method also resets the protected variable _stopRequested to false, so if a derived class overrides this method, then it should also do that. This method is read-synchronized on the workspace, so the preinitialize() method of the director need not be, assuming it is only called from here.
        Specified by:
        initialize in interface Initializable
        Overrides:
        initialize in class CompositeActor
        Throws:
        IllegalActionException - If there is no director, or if the director's preinitialize() method throws it, or if this actor is not opaque.

      • linkToPublishedPort

        public IOPort linkToPublishedPort​(java.lang.String name,
                                  IOPort subscriberPort)
                           throws IllegalActionException,
                                  NameDuplicationException
        Link the subscriberPort with a already registered "published port" coming from a publisher. The name is the name being used in the matching process to match publisher and subscriber. A subscriber interested in the output of this publisher uses the name. This registration process of publisher typically happens before the model is preinitialized, for example when opening the model. The subscribers will look for publishers during the preinitialization phase.
        Overrides:
        linkToPublishedPort in class CompositeActor
        Parameters:
        name - The name is being used in the matching process to match publisher and subscriber.
        subscriberPort - The subscribed port.
        Returns:
        the port that was created in the container.
        Throws:
        NameDuplicationException - If there are name conflicts as a result of the added relations or ports.
        IllegalActionException - If the published port cannot be found.

      • preinitialize

        public void preinitialize()
                   throws IllegalActionException
        Create receivers and invoke the preinitialize() method of the local director. If this actor is not opaque, throw an exception. This method also resets the protected variable _stopRequested to false, so if a derived class overrides this method, then it should also do that. This method is read-synchronized on the workspace, so the preinitialize() method of the director need not be, assuming it is only called from here.
        Specified by:
        preinitialize in interface Initializable
        Overrides:
        preinitialize in class CompositeActor
        Throws:
        IllegalActionException - If there is no director, or if the director's preinitialize() method throws it, or if this actor is not opaque.

      • registerPublisherPort

        public void registerPublisherPort​(java.lang.String name,
                                  IOPort port)
                           throws NameDuplicationException,
                                  IllegalActionException
        Register a "published port" coming from a publisher. The name is the name being used in the matching process to match publisher and subscriber. A subscriber interested in the output of this publisher uses the same name. This registration process of publisher typically happens before the model is preinitialized, for example when opening the model. The subscribers will look for publishers during the preinitialization phase.
        Overrides:
        registerPublisherPort in class CompositeActor
        Parameters:
        name - The name is being used in the matching process to match publisher and subscriber.
        port - The published port.
        Throws:
        NameDuplicationException - If the published port is already registered.
        IllegalActionException - If the published port can't be added.

      • stopFire

        public void stopFire()
        Request that execution of the current iteration complete. do nothing in this case
        Specified by:
        stopFire in interface Executable
        Overrides:
        stopFire in class CompositeActor

      • unlinkToPublishedPort

        public void unlinkToPublishedPort​(java.lang.String name,
                                  IOPort subscriberPort)
                           throws IllegalActionException
        Unlink the subscriberPort with a already registered "published port" coming from a publisher. The name is the name being used in the matching process to match publisher and subscriber. A subscriber interested in the output of this publisher uses the name. This registration process of publisher typically happens before the model is preinitialized, for example when opening the model. The subscribers will look for publishers during the preinitialization phase.
        Overrides:
        unlinkToPublishedPort in class CompositeActor
        Parameters:
        name - The name is being used in the matching process to match publisher and subscriber.
        subscriberPort - The subscribed port.
        Throws:
        IllegalActionException - If the published port cannot be found.

      • unregisterPublisherPort

        public void unregisterPublisherPort​(java.lang.String name,
                                    IOPort publisherPort)
                             throws IllegalActionException,
                                    NameDuplicationException
        Unregister a "published port" coming from a publisher. The name is the name being used in the matching process to match publisher and subscriber. A subscriber interested in the output of this publisher uses the same name. This registration process of publisher typically happens before the model is preinitialized, for example when opening the model. The subscribers will look for publishers during the preinitialization phase.
        Overrides:
        unregisterPublisherPort in class CompositeActor
        Parameters:
        name - The name is being used in the matching process to match publisher and subscriber. This will be the port that should be removed
        publisherPort - The publisher port.
        Throws:
        IllegalActionException - If thrown by the parent method.
        NameDuplicationException - If thrown by the parent method.

      • wrapup

        public void wrapup()
            throws IllegalActionException
        Invoke the wrapup() method of all the actors contained in the director's container. In this base class wrapup() is called on the associated actors in the order of their creation. If the container is not an instance of CompositeActor, then this method does nothing.

        This method should be invoked once per execution. None of the other action methods should be invoked after it in the execution. This method is not synchronized on the workspace, so the caller should be.

        Specified by:
        wrapup in interface Initializable
        Overrides:
        wrapup in class CompositeActor
        Throws:
        IllegalActionException - If the wrapup() method of one of the associated actors throws it.

      • getProfile

        public Profile getProfile()
        Return the profile for the composite actor.
        Returns:
        The profile.

      • _isPublishedPort

        protected boolean _isPublishedPort​(IOPort port)
        Return true if the port is a is connected to a publisher.
        Specified by:
        _isPublishedPort in class ModularCodeGenLazyTypedCompositeActor
        Parameters:
        port - The port to look up.
        Returns:
        Return true if the port is a is connected to a publisher.

      • _pubSubChannelName

        protected java.lang.String _pubSubChannelName​(IOPort port,
                                              boolean publisher,
                                              boolean subscriber)
        Return the name of a Publisher or Subscriber channel name.
        Specified by:
        _pubSubChannelName in class ModularCodeGenLazyTypedCompositeActor
        Parameters:
        port - The port.
        publisher - True if the corresponding Publisher should be returned.
        subscriber - True if the corresponding Subscriber should be returned.
        Returns:
        the name of the channel.