Package ptolemy.cg.lib

Class ModularCodeGenLazyTypedCompositeActor

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Configurable, Debuggable, DebugListener, Derivable, Instantiable, LazyComposite, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    ModularCodeGenTypedCompositeActor, ModularCompiledSDFTypedCompositeActor
    public abstract class ModularCodeGenLazyTypedCompositeActor
extends LazyTypedCompositeActor
    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)

    • Field Detail

      • recompileHierarchy

        public Parameter recompileHierarchy
        A boolean parameter to enforce recompilation of this ModularCodeGenTypedCompositeActor and all contained ModularCodeGenTypedCompositeActors.

      • recompileThisLevel

        public Parameter recompileThisLevel
        A boolean parameter to enforce recompilation of this ModularCodeGenTypedCompositeActor.

      • _addedSubscribersFromProfile

        protected boolean _addedSubscribersFromProfile
        True if subscribers were added from the profile.

      • _creatingPubSub

        protected int _creatingPubSub
        True if we Publishers or Subscribers are being created.

      • _generatingCode

        protected boolean _generatingCode
        True if code is being generated.

      • _fireMethod

        protected transient java.lang.reflect.Method _fireMethod
        The fire() method.

      • _objectWrapper

        protected java.lang.Object _objectWrapper
        The object wrapper.

      • _profile

        protected Profile _profile
        The profile.

      • _subscriberPorts

        protected java.util.Map<java.lang.String,​IOPort> _subscriberPorts
        Map of Subscriber ports. This is different thatn _subscribedPorts in CompositeActor.

    • Constructor Detail

      • ModularCodeGenLazyTypedCompositeActor

        public ModularCodeGenLazyTypedCompositeActor()
                                      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.

      • ModularCodeGenLazyTypedCompositeActor

        public ModularCodeGenLazyTypedCompositeActor​(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

      • classToActorName

        public static java.lang.String classToActorName​(java.lang.String className)
        Generate actor name from its class name.
        Parameters:
        className - The class name of the actor
        Returns:
        a String that declares the actor name

      • newRelation

        public ComponentRelation newRelation​(java.lang.String name)
                              throws NameDuplicationException
        Create a new relation with the specified name, add it to the relation list, and return it. Derived classes can override this to create domain-specific subclasses of ComponentRelation. This method is write-synchronized on the workspace and increments its version number. This overrides the base class to force evaluation of any deferred MoML. This is necessary so that name collisions are detected deterministically and so that order of relations does not change depending on whether evaluation has occurred.
        Overrides:
        newRelation in class LazyTypedCompositeActor
        Parameters:
        name - The name of the new relation.
        Returns:
        The new relation.
        Throws:
        NameDuplicationException - If name collides with a name already in the container.

      • _addEntity

        protected void _addEntity​(ComponentEntity entity)
                   throws IllegalActionException,
                          NameDuplicationException
        Add an entity or class definition to this container. This method should not be used directly. Call the setContainer() method of the entity instead. This method does not set the container of the entity to point to this composite entity. It assumes that the entity is in the same workspace as this container, but does not check. The caller should check. Derived classes may override this method to constrain the the entity to a subclass of ComponentEntity. This method is not synchronized on the workspace, so the caller should be. This overrides the base class to first populate the actor, if necessary, by calling populate(). This ensures that the entity being added now appears in order after the ones previously specified and lazily instantiated.
        Overrides:
        _addEntity in class LazyTypedCompositeActor
        Parameters:
        entity - Entity to contain.
        Throws:
        IllegalActionException - If the entity has no name, or the action would result in a recursive containment structure.
        NameDuplicationException - If the name collides with a name already in the entity.

      • _addRelation

        protected void _addRelation​(ComponentRelation relation)
                     throws IllegalActionException,
                            NameDuplicationException
        Add a relation to this container. This method should not be used directly. Call the setContainer() method of the relation instead. This method does not set the container of the relation to refer to this container. This method is not synchronized on the workspace, so the caller should be. This overrides the base class to first populate the actor, if necessary, by calling populate(). This ensures that the relation being added now appears in order after the ones previously specified and lazily instantiated.
        Overrides:
        _addRelation in class LazyTypedCompositeActor
        Parameters:
        relation - Relation to contain.
        Throws:
        IllegalActionException - If the relation has no name.
        NameDuplicationException - If the name collides with a name already on the contained relations list.

      • _fire

        protected void _fire​(java.util.List<java.lang.Object> argList)
              throws java.lang.Throwable
        Fire the actor.
        Parameters:
        argList - The arguments, true if there are outputs.
        Throws:
        java.lang.Throwable - If things go horrible wrong and the time/space continuum is broken.

      • _isPublishedPort

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

      • _isSubscribedPort

        protected boolean _isSubscribedPort​(IOPort port)
        Return true if the port is a is connected to a subscriber.
        Parameters:
        port - The port to look up.
        Returns:
        Return true if the port is a is connected to a subscriber.

      • _pubSubChannelName

        protected abstract java.lang.String _pubSubChannelName​(IOPort port,
                                                       boolean publisher,
                                                       boolean subscriber)
        Return the name of a Publisher or Subscriber channel name.
        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.

      • _removeEntity

        protected void _removeEntity​(ComponentEntity entity)
        Remove the specified entity. This method should not be used directly. Call the setContainer() method of the entity instead with a null argument. The entity is assumed to be contained by this composite (otherwise, nothing happens). This does not alter the entity in any way. This method is not synchronized on the workspace, so the caller should be. This overrides the base class to first populate the actor, if necessary, by calling populate(). This ensures that the entity being removed now actually exists.
        Overrides:
        _removeEntity in class LazyTypedCompositeActor
        Parameters:
        entity - The entity to remove.

      • _removeRelation

        protected void _removeRelation​(ComponentRelation relation)
        Remove the specified relation. This method should not be used directly. Call the setContainer() method of the relation instead with a null argument. The relation is assumed to be contained by this composite (otherwise, nothing happens). This does not alter the relation in any way. This method is not synchronized on the workspace, so the caller should be. This overrides the base class to first populate the actor, if necessary, by calling populate(). This ensures that the relation being removed now actually exists.
        Overrides:
        _removeRelation in class LazyTypedCompositeActor
        Parameters:
        relation - The relation to remove.

      • _setRecompileFlag

        protected void _setRecompileFlag()
                          throws IllegalActionException
        If configure is done, populating is not occurring, code is not being generated and Pub/Subs are not being created, then set the recompileThisLevel parameter to true. Otherwise, do nothing.
        Throws:
        IllegalActionException - If thrown while setting token.

      • _transferOutputs

        @Deprecated
protected static void _transferOutputs​(TypedCompositeActor compositeActor,
                                       IOPort port,
                                       java.lang.Object outputTokens)
                                throws IllegalActionException
        Deprecated.
        Invoke CompiledCompositeActor._transferOutputs() directly
        Transfer the outputs.
        Parameters:
        compositeActor - The composite actor transferring the outputs.
        port - The port on which the output is to be transferred
        outputTokens - The tokens to be transferred.
        Throws:
        IllegalActionException - If there are problems getting the class or otherwise transferring the tokens.