The Almagest 10-1Ptolemy Last updated: 10/9/97Chapter 10. Support for known listsand suchAuthors: Joseph T. BuckOther Contributors: Neil SmythPtolemy is an extensible system, and in quite a few places it must create objects given only thename of that object. There are therefore several classes that are responsible for maintaininglists: the list of all known domains, of all known blocks, states, targets, etc. As a general rule,these classes support aclone or makeNew method to create a new object based on its name(you cannot clone a domain, however).10.1 Class KnownBlockThe KnownBlock class is responsible for keeping a master list of all known types of Block ob-jects in the system. All member functions of KnownBlock are static; the only non-static func-tion of KnownBlock is the constructor. The KnownBlock constructor has the formKnownBlock(Block&block, const char*name);The only reason for constructing a KnownBlock object is for the side effects; the sideeffect is to addblock to the known block list for its domain under the namename, usingaddEntry. The reason for using a constructor for this purpose is that constructors forglobal objects are called before execution of the main program; constructors thereforeserve as a mechanism for execution of arbitrary initialization code for a module (as usedhere, “module” is an object file). Henceptlang, the Ptolemy star preprocessor, generatescode like the following for star definitions:static XXXMyClass proto;static KnownBlock entry(proto,"MyClass");This code adds a prototype entry of the class to the known list. Dynamically constructedblock types, such as interpreted galaxies, are added to the known list with a direct call toKnownBlock::addEntry. These cases should always supply an appropriate definition-source string so that conflicting block type definitions can be detected. KnownBlock keepstrack of the source of the definition of every known block type. This allows compile.c todetermine whether an Oct facet needs to be recompiled (without the source information,different facets that have the same base name could be mistaken for each other). This alsoallows us to generate some helpful warning messages when a block name is accidentallyre-used. The source location information is currently rather crude for everything exceptOct facets, but that’s good enough to generate a useful warning in nearly all cases. Known-Block assigns a sequential serial number to each definition or redefinition of a knownblock type. This can be used, for example, to determine whether a galaxy has been com-10-2 Support for known lists and suchU. C. Berkeley Department of EECSpiled more recently than any of its constituent blocks.static void addEntry (Block &block, const char*name, intonHeap, constchar*definitionSource);This function actually adds the block to the list. Separate lists are maintained for eachdomain; the block is added to the list corresponding to ‘block.domain()’. IfonHeap istrue, the block will be destroyed when the entry is removed or replaced from the list. defi-nitionSource should beNULL for any block type defined by C++ code (this is what ispassed by the KnownBlock constructor). It should be a hashstring’ed path name for ablock defined by an identifiable file (such as an Oct facet), or a special case constant stringfor other cases such as the ptcldefgalaxy command.static const Block* find (const char*name, const char*dom);The find method returns a pointer the appropriate block in the specified domain. A nullpointer is returned if no match is found.static Block* clone (const char*name, const char*dom);static Block* makeNew (const char*name, const char*dom);The clone method takes a string, finds the appropriate block in the specified domain, andreturns a clone of that block (theclone method is called on the block. This method, as arule, generates a duplicate of the block. ThemakeNew function is similar except that mak-eNew is called on the found block. As a rule, makeNew returns an object of the same class,but with default initializations (for example, with default state values). For either of these,an error message is generated (withError::abortRun) and a null pointer is returned ifthere is no match. To avoid a crash in the event of a self-referential galaxy definition,recursive clone or makeNew attempts are detected, and are terminated by generating anerror message and returning a null pointer.static StringList nameList (const char*domain);Return the names of known blocks in the given domain (second form). Names are sepa-rated by newline characters.static const char* defaultDomain ();Returns the default domain name. This is not used internally for anything; it is just set tothe first domain seen during the building of known lists.static int setDefaultDomain (const char*newval);Set the default domain name. Return FALSE if the specified value is not a valid domain.static int validDomain (const char*newval);Return TRUE if the given name is a valid domain.static int isDynamic (const char*type, const char*dom);Return TRUE if the named block is dynamically linked. There is an iterator associatedwith KnownBlock, called KnownBlockIter. It takes as an argument the name of a domain.The argument may be omitted, in which case the default domain is used. Itsnext functionreturns the typeconst Block*; it steps through the blocks on the known list for thatThe Almagest 10-3Ptolemy Last updated: 10/9/97domain.static int isDefined (const char*type, const char*dom,const char*definitionSource);If there is a known block of the given name and domain, return TRUE and pass back itsdefinition source string.static long serialNumber (const char*name, const char*dom);Look up a KnownBlock definition by name and domain, and return its serial number.Returns 0 iff no matching definition exists.static long serialNumber (Block&block);Given a block, find the matching KnownBlock definition, and return its serial number (or0 if no matching definition exists).10.2 Class KnownTargetThe KnownTarget class keeps track of targets in much the same way that KnownBlock keepstrack of blocks. There are some differences: there is only a single list of targets, not one perdomain as for blocks. The constructor works exactly the same way that the constructor forKnownBlock works; the codestatic MyTarget proto(args);static KnownTarget entry(proto,"MyTarget");adds the prototype instance to the known list with a call to addEntry.static void addEntry (Target&target, const char*name,