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;
The above functions return the number of ports, the number of multiports, or the number of states in the Block.
int numberMPHs() const;
int numberStates() const; 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);
These functions search the appropriate list and return a pointer to the contained object with the matching name.
PortHole* portWithName(const char* name);
MultiPortHole* multiPortWithName(const char* name);
virtual State *stateWithName(const char* 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,
Get a list of multiport names.
int* io, int nMax) const; 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();
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
virtual const Star& asStar() const; 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;}
The distinction between
virtual Block* clone() const 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)
Add a porthole, or a multiporthole, to the block's list of known ports or multiports.
void addPort(MultiPortHole& port) 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.