Domain can use the various classes mentioned above as they exist in the Ptolemy kernel or it can redefine them as needed. For example, in the SDF domain, the classes SDFStar, SDFPortHole, SDFScheduler, SDFDomain, SDFTarget, and SDFWormhole have all been defined. Most of those classes inherit much of their functionality from the corresponding kernel classes but the Domain creator is free to make major changes as well. The kernel Geodesic, Plasma, and Particle classes are used without modification, but other domains such as the CG domain have derived a subclass from Geodesic. The Domain creator needs to decide whether or not existing Ptolemy classes can be used without change, therefore it is a good idea to understand what functionality the kernel classes provide.The following is a brief description of the various classes that either need to be defined or are used by a
Domain. Note that we only provide a functional description of some of the major methods of each class and not a complete description of all methods.
Target is an object that manages the execution of the Stars in a Domain. Major methods:
run() Called to execute a schedule.
wrapup() Called at the end of an execution to clean up.
setup() Called by initialize() (which is inherited from the Block class, which is a common base class for many of Ptolemy's classes). Sets each Star to point to this Target and sets up the Scheduler.
gal A pointer to the Galaxy being executed.
sched A pointer to the Scheduler that is being used.
Targets, see some of the existing domains.
Domain, like which type of WormHole, PortHole, Star, etc. is used by the Domain.Major methods:
newWorm() Create a WormHole of the appropriate type for this Domain.
newFrom() Create an EventHorizon (an object that is used to interface to other Domains, used with WormHoles) that translates data from a Universal format to a Domain specific one.
newTo() Create an EventHorizon that translates data from a Domain specific format to a Universal one.
newNode() Returns a Geodesic of the appropriate type for this Domain.
Star is an object derived from class Block that implements an atomic function. Major methods:
run() What to do to run the star.
DataFlowStar class (a parent class to many of the dataflow domain stars such as SDFStar and DDFStar) defines this function to make each input PortHole obtain Particles from the Geodesic, execute the go() method of each Star, and then have each output PortHole put its Particles into the Geodesic.
PortHoles are data members of Stars and are where streams of Particles enter or leave the Stars. Each PortHole always handles Particles of one type, so two connected PortHoles need to decide which data type they will use if they are not the same. There is a base class called GenericPort which provides some basic methods that derived classes should redefine as well as some data members commonly needed by all PortHole types. Major methods:
isItInput() Return TRUE if the PortHole class is an input type.
isItOutput() Return TRUE if the PortHole class is an output type.
isItMulti() Return TRUE if the PortHole class is a MultiPorthole.
connect() Connect this PortHole to a Geodesic (create one if needed) and tell that Geodesic to connect itself to both this PortHole and the destination PortHole. Also provides the number of delays on this connection.
initialize() Initialize the PortHole. In the case of output PortHoles, this function will usually initialize the connected Geodesic as well. Resolve the type of Particles with the PortHole it is connected to.
receiveData() What to do to receive data from the Geodesic.
sendData() What to do to send data to the Geodesic.
putParticle() Put a particle from the buffer into the Geodesic.
getParticle() Get a particle from the Geodesic and put it into the buffer.
numXfer() Returns numberTokens, the number of Particles transferred per execution.
numTokens() Returns the number of Particles inside the Geodesic.
numInitDelays() Returns the number of initial delay on the Geodesic.
geo() Returns a pointer to the Geodesic this PortHole is connected to.
setDelay() Set the delay on the Geodesic.
myType Data type of particles in this porthole.
myGeodesic The Geodesic that this PortHole is connected to
myPlasma A pointer to the Plasma used to request new Particles.
myBuffer Usually a CircularBuffer used to store incoming or outgoing Particles.
farSidePort The PortHole that we are connected to.
bufferSize The size of the Buffer.
numberTokens The number of Particles consumed or generated each time we access the Geodesic.
PortHoles are generally separated into input PortHoles and output PortHoles. They aren't designed to handle bidirectional traffic.
PortHoles. Major methods:
setSourcePort() Set the source PortHole and the delay on this connection. A delay is usually implemented as an initial Particle in the Geodesic's buffer, but this can be changed depending on the desired functionality.
setDestPort() Set the destination PortHole.
disconnect() Disconnect from the given PortHole.
setDelay() Set the number of delays on this connection.
initialize() Initialize the buffer in this Geodesic. This means either clear it or insert the number of initial Particles needed to match the number of delays on this connection (these Particles are taken from the source PortHoles's Plasma).
put() Put a Particle into the buffer
get() Get a Particle from the buffer. incCount() and decCount() are used by a Scheduler to simulate an execution.
numInit() Return the number of initial particles.
originatingPort A pointer to the source PortHole.
destinationPort A pointer to the destination PortHole.
pstack The buffer, implemented as a ParticleStack.
sz The number of Particles in the buffer.
numInitialParticles Particles. There is one global instance of a Plasma for each type of Particle defined in the kernel. This class is usually only used by the Domains and not changed by the authors of new Domains.Major methods:
put() Return an unused Particle to the Plasma.
get() Get an unused Particle (or create one if needed).
Particle types supported by Ptolemy. Currently, the types are Float, Int, Complex, Fix, and Message. The Message Particle is used to carry Messages (inside Envelopes) which can be almost anything. For example, the Matrix class is transferred using Message Particles. These classes are also only used as-is by the Domains and not redefined for new domains.
Star of the Galaxy will fire. Execution is performed using two main methods -- setup() and run(). Schedulers can be timed or untimed, depending on the Domain's model of execution. This class will usually be different for each domain, although some domains reuse the Scheduler of another domain, if the Scheduler is appropriate for the new domain's model of computation.Major methods:
setup() Checks the Stars in the Galaxy, initializes them, and creates a schedule.
run() Run the schedule computed in setup()
myGalaxy The pointer to the Galaxy that the Scheduler is working on.
myTarget The pointer to the Target which is controlling the execution.