Top Up Prev Next Bottom Contents Index Search

3.1 Class Block

Block is the basic object for representing an actor in Ptolemy. It is derived from NamedObj (see section 1.8). Important derived types of Block are Star (see section 3.2), representing an atomic actor; Galaxy , representing a collection of actors that can be thought of as one actor, and Universe , representing an entire runnable system. A Block has portholes (connections to other blocks - , states (parameters and internal states - , and multiportholes (organized collections of portholes - . While the exact data structure used to represent each is a secret of class Block, it is visible that there is an order to each list, in that iterators return the contained states, portholes, and multiportholes in this order. Iterators are a set of helper classes that step through the states, portholes, or multiportholes that belong to the Block, see the menu entry. Furthermore, Blocks can be cloned, an operation that produces a duplicate block. There are two cloning functions: makeNew, which resembles making a new block of the same class, and clone, which makes a more exact duplicate (with the same values for states, for example). This feature is used by the KnownBlock class to create blocks on demand.

3.1.1 Block constructors and destructors

Block has a default constructor, which sets the name and descriptor to empty strings and the parent pointer to null, and a three-argument constructor:

Block(const char* name,Block* parent, const char* descriptor); 
Block's destructor is virtual and does nothing, except for the standard action of destroying the Block's data members. In addition, Block possesses two types of "virtual constructors", the public member functions makeNew and clone.

3.1.2 Block public "information" members

int numberPorts() const;
int numberMPHs() const;
int numberStates() const;
The above functions return the number of ports, the number of multiports, or the number of states in the Block.

virtual int isItAtomic() const; 
virtual int isItWormhole() const; 
These functions return TRUE or FALSE, based on whether the Block is atomic or not, or a wormhole or not. The base implementations return TRUE for isItAtomic, FALSE for isItWormhole.

virtual StringList print(int verbose) const; 
Overrides NamedObj::print. This function gives a basic printout of the information in the block.

GenericPort* genPortWithName(const char* name);
PortHole* portWithName(const char* name);
MultiPortHole* multiPortWithName(const char* name);
virtual State *stateWithName(const char* name);
These functions search the appropriate list and return a pointer to the contained object with the matching name. genPortWithName searches both the multiport and the regular port lists (multiports first). If a match is found, it returns a pointer to the matching object as a GenericPort pointer.

int multiPortNames (const char** names, const char** types,
int* io, int nMax) const;
Get a list of multiport names.

StringList printPorts(const char* type, int verbose) const; 
Print portholes as part of the info-printing method.

virtual Scheduler* scheduler() const; 
Return the controlling scheduler for this block. The default implementation simply recursively calls the scheduler() function on the parent, or returns 0 if there is no parent. The intent is that eventually a block with a scheduler will be reached (the top-level universe has a scheduler, and so do wormholes).

virtual Star& asStar(); 
virtual const Star& asStar() const;
Return reference to me as a Star, if I am one. Warning: it is a fatal error (the entire program will halt with an error message) if this method is invoked on a Galaxy! Check with isItAtomic before calling it.

virtual Galaxy& asGalaxy(); 
virtual const Galaxy& asGalaxy() const; 
Return reference to me as a Galaxy, if I am one. Warning: it is a fatal error (the entire program will halt) if this method is invoked on a Star! Check with isItAtomic before calling it.

virtual const char* domain() const; 
Return my domain (e.g. SDF, DE, etc.)

3.1.3 Other Block public members

virtual void initialize(); 
overrides NamedObj::initialize. Block::initialize initializes the portholes and states belonging to the block, and calls setup(), which is intended to be the "user-supplied" initialization function.

virtual void preinitialize(); 
Perform a "pre-initialization" step. The default implementation does nothing. This method is redefined by HOF stars and other stars that need to rewire a galaxy before the main initialization phase starts. Blocks must act safely if preinitialized multiple times (unless they remove themselves from the galaxy when preinitialized, as the HOF stars do). Preinitialize is invoked by Galaxy::preinitialize, which see.

virtual int run(); 
This function is intended to "run" the block. The default implementation does nothing.

virtual void wrapup(); 
This function is intended to be run after the completion of execution of a universe, and provides a place for wrapup code. The default does nothing.

virtual Block& setBlock(const char* name,Block* parent=0); 
Set the name and parent of a block.

virtual Block* makeNew() const 
This is a very important function. It is intended to be overloaded in such a way that calling it produces a newly constructed object of the same type. The default implementation causes an error. Every derived type should redefine this function. Here is an example implementation of an override for this function:

Block* MyClass::makeNew() const { return new MyClass;}
virtual Block* clone() const
The distinction between clone and makeNew is that the former does some extra copying. The default implementation calls makeNew and then copyStates, and also copies additional members like flags; it may be overridden in derived classes to copy more information. The intent is that clone should produce an identical object.

void addPort(PortHole& port) 
void addPort(MultiPortHole& port)
Add a porthole, or a multiporthole, to the block's list of known ports or multiports.

int removePort(PortHole& port) 
Remove port from the Block's port list, if it is present. 1 is returned if port was present and 0 is returned if it was not. Note that port is not deleted. The destructor for class PortHole calls this function on its parent block.

void addState(State& s); 
Add the state s to the Block's state list.

virtual void initState(); 
Initialize the States contained in the Block's state list.

StringList printStates(const char* type,int verbose) const; 
Return a printed representation of the states in the Block. This function is used as part of the Block's print method.

int setState(const char* stateName, const char* expression); 
Search for a state in the block named stateName. If not found, return 0. If found, set its initial value to expression and return 1.

3.1.4 Block protected members

virtual void setup(); 
User-specified additional initialization. By default, it does nothing. It is called by Block::initialize (and should also be called if initialize is redefined).

Block* copyStates(const Block& src); 
method for copying states during cloning. It is designed for use by clone methods, and it assumes that the src argument has the same state list as the this object.

3.1.5 Block iterator classes

There are three types of iterators that may be used on Blocks: BlockPortIter, BlockStateIter, and BlockMPHIter. Each takes one argument for its constructor, a reference to Block. They step through the portholes, states, or multiportholes, of the Block, respectively, using the standard iterator interface. There are also variant versions with a "C" prefix (CBlockPortIter, etc) defined in the file ConstIters.h that take a reference to a const Block and return a const pointer.

Top Up Prev Next Bottom Contents Index Search
Copyright © 1990-1997, University of California. All rights reserved.