KnownBlock(Block& block, const char* name);The only reason for constructing a KnownBlock object is for the side effects; the side effect is to add
block to the known block list for its domain under the name name, using addEntry. The reason for using a constructor for this purpose is that constructors for global objects are called before execution of the main program; constructors therefore serve as a mechanism for execution of arbitrary initialization code for a module (as used here, "module" is an object file). Hence ptlang, the Ptolemy star preprocessor, generates code 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 constructed block types, such as interpreted galaxies, are added to the known list with a direct call to
KnownBlock::addEntry. These cases should always supply an appropriate definition-source string so that conflicting block type definitions can be detected.KnownBlock keeps track of the source of the definition of every known block type. This allows compile.c to determine 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 also allows us to generate some helpful warning messages when a block name is accidentally re-used. The source location information is currently rather crude for everything except Oct facets, but that's good enough to generate a useful warning in nearly all cases.
KnownBlock also assigns a sequential serial number to each definition or redefinition of a known block type. This can be used, for example, to determine whether a galaxy has been compiled more recently than any of its constituent blocks.
static void addEntry (Block & block, const char* name, int onHeap, const char* definitionSource);This function actually adds the block to the list. Separate lists are maintained for each domain; the block is added to the list corresponding to `
block.domain()'. If onHeap is true, the block will be destroyed when the entry is removed or replaced from the list. definitionSource should be NULL for any block type defined by C++ code (this is what is passed by the KnownBlock constructor). It should be a hashstring'ed path name for a block defined by an identifiable file (such as an Oct facet), or a special case constant string for other cases such as the ptcl defgalaxy 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 null pointer is returned if no match is found.
static Block* clone (const char* name, const char* dom);The
static Block* makeNew (const char* name, const char* dom);
clone method takes a string, finds the appropriate block in the specified domain, and returns a clone of that block (the clone method is called on the block. This method, as a rule, generates a duplicate of the block. The makeNew function is similar except that makeNew 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 (with Error::abortRun) and a null pointer is returned if there 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 an error 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 separated by newline characters.
static const char* defaultDomain ();Returns the default domain name. This is not used internally for anything; it is just set to the 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 associated with 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. Its
next function returns the type const Block*; it steps through the blocks on the known list for that domain.
static int isDefined (const char* type, const char* dom,If there is a known block of the given name and domain, return TRUE and pass back its definition source string.
const char &definitionSource);
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 (or 0 if no matching definition exists).