.\" @(#)design	1.6 12/12/92
.H1 "Domain Design"
.pp
.IE "domain design"
Data abstraction and polymorphism, two tenets of object-oriented
programming, allow domains (corresponding to models of computation)
to be abstracted
so that their differences are not visible from the kernel.
Domains can be selectively linked into \*(PT,
and the mere action of linking them makes them visible and usable.
\*(PT executables can therefore be created that are
tuned to a particular application.  For example,
if we are interested only in simulation of communication networks, we can
link only the DE and the SDF domains to the kernel, 
excluding other domains.
.pp
To define a new domain, it is necessary to define a base class
for the stars in the domain, a set of classes
for interconnecting stars in the domain and passing data
between them, a scheduler, one or more targets, a wormhole, a mechanism for
connecting to other domains through the wormhole boundary,
and a domain object.
This is no small task.
However, all of these objects have well-defined base classes
from which the new classes must be derived, and most new domains
make only very minor additions or changes to these base classes.
Major changes, however, are possible, and may be required to introduce
domains that operate in very different ways compared to the existing
domains.
.pp
To make the task of producing a new domain a bit easier, we include
a sample ``dummy domain'' named ``XXX'' in the directory
``~ptolemy/src/domains/xxx/kernel''.
.pp
There is a great deal of flexibility in the definition of new domains,
and only the \*(PT source code can provide full documentation.
If the \fIptlang\fR preprocessor is to be used with a new domain,
however, then there is less flexibility.
This preprocessor generates C++ code that assumes that certain
classes have been defined.  These classes normally contain
the domain name as part of their class name, e.g.
.c SDFStar ,
and
.c InSDFPort .
Hence when defining a new domain, many new classes have to be defined.
Of course, if these are identical to existing classes, the definition
may be very simple, as in the following example:
.(c
#define XXXGeodesic AutoForkNode
.)c
In this example, a
.c Geodesic
has been defined for a new domain ``XXX'' to be identical
to a class defined in the kernel,
.c AutoForkNode .
.pp
A domain has a specific operational semantics for a block diagram
representation.  The operational semantics are realized by a
.c Scheduler
for the domain, so in some sense this forms the heart
of the domain.  The scheduler
determines when to fire the blocks in an application.
This determination can be made statically or dynamically.
For that purpose, the
.c Scheduler
base class has two methods: \fIsetup()\fR (for operations done once
before a run, such as static scheduling), and
\fIrun()\fR (for dynamically invoking blocks).
The \fIrun()\fR method fires blocks under its control until
a stopping condition is met.
.IE "run() scheduler method"
.IE "setup() scheduler method"
Two different methods are provided to specify the stopping condition for
the run.
If the domain is that of a
.c Universe ,
we call the \fIsetStopTime()\fR method.  If the domain resides in a
.c Wormhole ,
we call the \fIresetStopTime()\fR method.
.IE "setStopTime() scheduler method"
.IE "resetStopTime() scheduler method"
.pp
Control of execution of a universe is accomplished by a
.c Target .
In most simulation domains, the
.c Target
object simply passes commands through to the
.c Scheduler
object; it may also be used to pass parameters through to the
scheduler.  In code generation domains, in particular, different
.c Target
objects model different targets for the generated code.
.pp
It may also be necessary to define domain specific star and
.c PortHole
classes.
For example, the 
stars and portholes
in the DE domain need to keep timing information while those
in the SDF domain need not.
They may also have some members and methods accessed by the 
.c Scheduler
in the domain.  An example is the \fIrepetitions\fR in the 
.c SDFStar
class, which
indicates how many times the
star will be executed in one iteration.  It is required by the scheduler
during the setup phase to perform static scheduling.
Similarly the
.c SDFPortHole
class contains methods for setting parameters that are specific
to SDF, such as the number of
.c Particle s
consumed or produced on a porthole when the star fires.
.pp
To get a new domain to interact with existing domains, it
is necessary to define
.c Wormhole
and
.c EventHorizon
classes.
It is worth noting that a domain may do without the
.c Wormhole
class if the domain will never contain other domains inside.
.IE Wormhole
.IE EventHorizon
However, the
.c EventHorizon
class is required for the domain to be an inner domain of a
wormhole.
An event horizon actually consists of a pair of classes,
.c XXXtoUniversal
and
.c XXXfromUniversal ,
where
.c XXX
is the domain name.
.IE toUniversal
.IE fromUniversal
These classes are placed in the input or output port of a
wormhole
depending on the direction of dataflow.
Further details of these classes are given below.
.pp
An additional class defined in a domain is the
.c Domain
class.
.IE "Domain class"
Its definition are straightforward but essential for
domain abstraction in the kernel.  The source code
for the base class in the kernel is self-explanatory,
so it serves as the best reference.
Wormhole design, however, is much more subtle,
and hence is explained in more detail below.
.pp
A complete domain definition also consists of a library of stars.
However, the design of these stars is entirely up the domain
designer, so there is little guidance we can provide.
Note that for many new domains, it will be possible to use
the
.i ptlang
preprocessor unchanged for the design of stars.
This is encouraged because it promotes uniformity.
The preprocessor also produces documentation for stars.

