4.6 Writing Stars That Manipulate Any Particle Type

Ptolemy allows stars to declare that inputs and outputs are of type ANYTYPE. A star
may need to do this, for example, if it simply copies its inputs without regard to type, as in the
case of a Fork star, or if it calls a generic function that is overloaded by every data type, such
as sink stars which call the print method of the type.

The following is an example of a star that operates on ANYTYPE particles:

defstar {
name {Fork}
domain {SDF}
desc { Copy input particles to each output. }
input {
name{input}
type{ANYTYPE}
}
outmulti {
name{output}
type{= input}
}
go {
MPHIter nextp(output);
PortHole* p;
while ((p = nextp++) != 0)
(*p)%0 = input%0;
}
}

Notice how in the definition of the output type, the star simply says that its output type will be the same as the input type. ptlang translates this definition into an ANYTYPE output porthole and a statement in the star constructor that reads

output.inheritTypeFrom(input); as you can see by examining the .cc file generated for SDFFork.

During galaxy setup, the Ptolemy kernel assigns actual types to ANYTYPE portholes, making use of the types of connected portholes and inheritTypeFrom connections. For example, if a Fork's input is connected to an output porthole of type INT, the Fork's input becomes type INT, and then so do its output(s) thanks to the inheritTypeFrom connection. At runtime there is no such thing as an ANYTYPE porthole; every porthole has been resolved to some specific data type, which can be obtained from the porthole using the resolvedType() method. (However, this mechanism does not distinguish among the various subclasses of Message, so if you are using Message particles you still need to check the actual type of each Message received.)

Porthole type assignment is really a fairly complex and subtle algorithm, which is discussed further in the Ptolemy Kernel Manual. The important properties for a star writer to know are these:

If an input port has a specific declared type, it is guaranteed to receive particles of that type. For reasons mentioned in "Reading inputs and writing outputs" on page 2-17, it is safest to explicitly cast input particles to the desired type, as in

go {
double value = double(in%0);
...
} but this is not strictly necessary in the current system.

In simulation domains, an output port is NOT guaranteed to transmit particles of its declared type; the actual resolved type of the porthole will be determined by the connected input porthole. Therefore, you should always allow for type conversion of the value computed by the star into the actual type of the output particle. This happens implicitly when you write something like
out%0 << t;because this expands into a call of the particle's virtual method for loading a value of the given type. But assuming that you know the exact type of particle in the porthole --- say by writing something like (FloatParticle&) (out%0) --- is very unsafe.
In code generation domains, it is usually critical that the output porthole's actual type be what the star writer expected. Most codegen domains therefore splice type conversion stars into the schematic when input and output ports of different declared types are connected. In this way, both connected stars will see the data type they expect, and the necessary type conversion is handled transparently.
The component portholes of a multiporthole are type-resolved separately. Thus, if an input multiporthole is declared ANYTYPE, its component portholes might have different types at runtime. (This was not true in Ptolemy versions preceding 0.7.) The component portholes of an output multiporthole can have different resolved types in any case, because they might be connected to inputs of different types.
It is rarely a good idea to declare a pure ANYTYPE output porthole; rather, its type should be equated to some input porthole using the ptlang = port notation or an explicit inheritTypeFrom call. This ensures that the type resolution algorithm can succeed. A "pure ANYTYPE" output will work only if connected to an input of determinable type; if it's connected to an ANYTYPE input, the kernel will be unable to resolve a type for the connection. By providing an = type declaration, you allow the kernel to choose an appropriate particle type for an ANYTYPE-to-ANYTYPE connection.