3.3 Class Galaxy

A Galaxy is a type of Block that has an internal hierarchical structure. In particular, it contains other Blocks (some of which may also be galaxies). It is possible to access only the top-level blocks or to flatten the hierarchy and step through all the blocks, by means of the various iterator classes associated with Galaxy. While we generally define a different derived type of Star for each domain, the same kinds of Galaxy (and derived classes such as InterpGalaxy - are used in each domain. Accordingly, a Galaxy has a data member containing its associated domain (which is set to null by the constructor). PortHoles belonging to a Galaxy are, as a rule, aliased so that they refer to PortHoles of an interior Block, although this is not a requirement.

3.3.1 Galaxy public members

void initialize();

System initialize method. Derived Galaxies should not redefine initialize; they should write a setup() method to do any class-specific startup.

virtual void preinitialize();

Preinitialization of a Galaxy invokes preinitialization of all its member blocks. Preinitialization of the member blocks is done in two passes: the first pass preinits atomic blocks only, the second all blocks. This allows clean support of graphical recursion; for example, a HOFIfElseGr star can control a recursive reference to the current galaxy. The IfElse star is guaranteed to get control before the subgalaxy does, so it can delete the subgalaxy to stop the recursion. The second pass must preinit all blocks in case a non-atomic block adds a block to the current galaxy. Galaxy::preinitialize is called from Galaxy::initialize. (It would be somewhat cleaner to have the various schedulers invoke preinitialize() separately from initialize(), but that would require many more pieces of the system to know about preinitialization.) Because of this decision, blocks in subgalaxies will see a preinitialize call during the outer galaxy's preinitialize pass and then another one when the subgalaxy is itself initialized. Thus, blocks must act safely if preinitialized multiple times. (HOF stars generally destroy themselves when preinitialized, so they can't see extra calls.)

void wrapup();

System wrapup method. Recursively calls wrapup in subsystems

void addBlock(Block& b,const char* bname);

Add block to the galaxy and set its name.

int removeBlock(Block& b);

Remove the block b from the galaxy's list of blocks, if it is in the list. The block is not deleted. If the block was present, 1 is returned; otherwise 0 is returned.

virtual void initState();

Initialize states.

int numberBlocks() const;

Return the number of blocks in the galaxy.

StringList print(int verbose) const;

Print a description of the galaxy.

int isItAtomic() const;

Returns FALSE (galaxies are not atomic blocks).

Galaxy& asGalaxy();
const Galaxy& asGalaxy() const;

These return myself as a Galaxy, overriding Block::asGalaxy.

const char* domain() const;

Return my domain.

void setDomain(const char* dom);

Set the domain of the galaxy (this may become a protected member in the future).

Block* blockWithName(const char* name);

Support blockWithName message to access internal block list.

3.3.2 Galaxy protected members

void addBlock(Block& b)

Add b to my list of blocks.

void connect(GenericPort& source, GenericPort& destination,
             int numberDelays = 0)

Connect sub-blocks with a delay (default to zero delay).

void alias(PortHole& galPort, PortHole& blockPort); 
void alias(MultiPortHole& galPort, MultiPortHole& blockPort);

Connect a Galaxy PortHole to a PortHole of a sub-block, or same for a MultiPortHole.

void initSubblocks(); 
void initStateSubblocks();

Former: initialize subblocks only. Latter: initialize states in subblocks only.

3.3.3 Galaxy iterators

There are three types of iterators associated with a Galaxy: GalTopBlockIter, GalAllBlockIter, and GalStarIter. The first two iterators return pointers to Block; the final one returns a pointer to Star. As its name suggests, GalTopBlockIter returns only the Blocks on the top level of the galaxy. GalAllBlockIter returns Blocks at all levels of the hierarchy, in depth-first order; if there is a galaxy inside the galaxy, first it is returned, then its contents are returned. Finally, GalStarIter returns only the atomic blocks in the Galaxy, in depth-first order. There is also a const form of GalTopBlockIter, called CGalTopBlockIter. Here is a function that prints out the names of all stars at any level of the given galaxy onto a given stream.

void printNames(Galaxy& g,ostream& stream) { 
    GalStarIter nextStar(g); 
    Star* s; 
    while ((s = nextStar++) != 0) 
        stream << s->fullName() << "\back n";