Top Up Prev Next Bottom Contents Index Search

3.5 Class InterpGalaxy


InterpGalaxy is derived from DynamicGalaxy. It is the key workhorse for interfacing between user interfaces, such as ptcl or pigi, and the Ptolemy kernel, because it has commands for building structures given commands specified in the form of text strings. These commands add stars and galaxies of given types and build connections between them. InterpGalaxy interacts with the KnownBlock class to create stars and galaxies, and the Domain class to create wormholes. InterpGalaxy differs from other classes derived from Block in that the "class name" (the value returned by className()) is a variable; the class is used to create many different "derived classes" corresponding to different topologies. In order to use InterpGalaxy to make a user-defined galaxy type, a series of commands are executed that add stars, connections, and other features to the galaxy. When a complete galaxy has been designed, the addToKnownList member function adds the complete object to the known list, an action that has the effect of adding a new "class" to the system. InterpGalaxy methods that return an int return 1 for success and 0 for failure. On failure, an appropriate error message is generated by means of the Error class.

3.5.1 Building structures with InterpGalaxy

The no-argument constructor creates an empty galaxy. There is a constructor that takes a single const char * argument specifying the class name (the value to be returned by className(). The copy constructor creates another InterpGalaxy with the identical internal structure. There is also an assignment operator that does much the same.

void setDescriptor(const char* dtext) 
Set the descriptor. Note that this is public, though the NamedObj function is protected. dtext must live as long as the InterpGalaxy does.

int addStar(const char* starname, const char* starclass); 
Add a new star or galaxy with class name starclass to this InterpGalaxy, naming the new instance starname. The known block list for the current domain is searched to find starclass. Returns 1 on success, 0 on failure. On failures, an error message of the form

No star/galaxy named 'starclass' in domain 'current-domain'

will be produced. The name is a misnomer since starclass may name a galaxy or a wormhole.

int connect(const char* srcblock, const char* srcport,
const char* dstblock, const char* dstport,
const char* delay = 0);
This method creates a point-to-point connection between the port srcport in the subblock srcblock and the port dstport in the subblock dstblock, with a delay value represented by the expression delay. If the delay parameter is omitted there is no delay. The delay expression has the same form as an initial value for an integer state (class IntState), and is parsed in the same way as an IntState belonging to a subblock of the galaxy would be. 1 is returned for success, 0 for failure. A variety of error messages relating to nonexistent blocks or ports may be produced.

int busConnect(const char* srcblock, const char* srcport,
const char* dstblock, const char* dstport,
const char* width, const char* delay = 0);
This method creates a point-to-point bus connection between the multiport srcport in the subblock srcblock and the multiport dstport in the subblock dstblock, with a width value represented by the expression width and delay value represented by the expression delay. If the delay parameter is omitted there is no delay. A bus connection is a series of parallel connections: each multiport contains width portholes and all are connected in parallel. The delay and width expressions have the same form as an initial value for an integer state (class IntState), and are parsed in the same way as an IntState belonging to a subblock of the galaxy would be. 1 is returned for success, 0 for failure. A variety of error messages relating to nonexistent blocks or multiports may be produced.

int alias(const char* galport, const char* block, const char *blockport); 
Create a new port for the galaxy and make it an alias for the porthole blockport contained in the subblock block. Note that this is unlike the Galaxy alias method in that this method creates the galaxy port.

int addNode(const char* nodename); 
Create a node for use in netlist-style connections and name it nodename.

int nodeConnect(const char* blockname, const char* portname,
const char* node, const char* delay = 0);
Connect the porthole named portname in the subblock named blockname to the node named node. Return 1 for success, 0 and an error message for failure.

int addState(const char* statename, const char* stateclass, 
const char* statevalue);
Add a new state named statename, of type stateclass, to the galaxy. Its default initial value is given by statevalue.

int setState(const char* blockname, const char* statename, 
const char* statevalue);
Change the initial value of the state named statename that belongs to the subblock blockname to the string given by statevalue. As a special case, if blockname is the string this, the state belonging to the galaxy, rather than one belonging to a subblock, is changed.

int setDomain(const char* newDomain); 
Change the inner domain of the galaxy to newDomain. This is the technique used to create wormholes (that are one domain on the outside and a different domain on the inside). It is not legal to call this function if the galaxy already contains stars.

int numPorts(const char* blockname, const char* portname, int numP); 
Here portname names a multiporthole and blockname names the block containing it. numP portholes are created within the multiporthole; these become ports of the block as a whole. The names of the portholes are formed by appending #1, #2, etc. to the name of the multiporthole.

3.5.2 Deleting InterpGalaxy structures

int delStar(const char* starname); 
Delete the instance named starname from the current galaxy. Ports of other stars that were connected to ports of starname will become disconnected. Returns 1 on success, 0 on failure. On failure an error message of the form

No instance of ``starname'' in ``galaxyname''

will be produced. The name is a misnomer since starclass may name a galaxy or a wormhole.

int disconnect(const char* block, const char* port); 
Disconnect the porthole port, in subblock block, from whatever it is connected to. This works for point-to-point or netlist connections.

int delNode(const char* nodename); 
Delete the node nodename.

3.5.3 InterpGalaxy and cloning

Block *makeNew() const; 
Block *clone() const;
For InterpGalaxy the above two functions have the same implementation. An identical copy of the current object is created on the heap.

void addToKnownList(const char* definitionSource,
const char* outerDomain,
Target* innerTarget = 0);
This function adds the galaxy to the known list, completing the definition of a galaxy class. The "class name" is determined by the name of the InterpGalaxy (as set by Block::setBlock or in some other way). This class name will be returned by the className function, both for this InterpGalaxy and for any others produced from it by cloning. If outerDomain is different from the system's current domain (read from class KnownBlock), a wormhole will be created. A wormhole will also be created if innerTarget is specified, or if galaxies for the domain outerDomain are always wormholes (this is determined by asking the Domain class). Once addToKnownList is called on an InterpGalaxy object, that object should not be modified further or deleted. The KnownBlock class will manage it from this point on. It will be deleted if a second definition with the same name is added to the known list, or when the program exits.

3.5.4 Other InterpGalaxy functions

const char* className() const 
Return the current class name (which can be changed). Unlike most other classes, where this function returns the C++ class name, we consider the class name of galaxies built by InterpGalaxy to be variable; it is set by addToKnownList and copied from one galaxy to another by the copy constructor or by cloning.

void preinitialize(); 
Overrides Galaxy::preinitialize(). This re-executes initialization steps that depend on variable parameters, such as delays and bus connections for which the delay value or bus width is an expression with variables. Galaxy::preinitialize is then invoked to preinitialize the member blocks.

Block* blockWithDottedName(const char* name); 
Returns a pointer to an inner block, at any depth, whose name matches the specification name. For example, blockWithDottedName("a.b.c") would look first for a subgalaxy named "a", then within that for a subgalaxy named "b", and finally with that for a subgalaxy named "c", returning either a pointer to the final Block or a null pointer if a match is not found.



Top Up Prev Next Bottom Contents Index Search

Copyright © 1990-1997, University of California. All rights reserved.