[kepler-dev] IOPort.send() can now take a null token

[Edward A. Lee]

If you have written your own Receiver for a specialized
domain, and that Receiver is not in the Ptolemy II tree,
and you want your domain to work with other Ptolemy II
domains such as SR and Continuous, you will want to read
on. If not, then reading on might give you a headache...

A demo in the continuous domain (HybridPlant) exposed
a problem with the token transport mechanism in Ptolemy II
(IOPort and Receiver). Not really a bug, but rather a
mechanism that made it difficult to achieve domain
polymorphism, and hence difficult to ensure that domains
would play well together in arbitrary hierarchical combinations.

The HybridPlant demo combines DE, modal models,
and the continuous domain.

The problem is that some actors that are non-strict (they
can fire even when not all inputs are known) need to be able
to assert that an output is "absent." Continuous is such a
domain (as is SR). The mechanism we were
using to achieve this was IOPort.sendClear(). However, the
documentation for IOPort.sendClear() says this:

*  Set all destination receivers connected via the specified
*  to channel to have no token.

This achieves the desired effect in SR and Continuous, but
in domain where tokens are queued (DE, SDF, PN, etc.), it
is disastrous. It introduces nondeterminism. Previously,
it was up to an actor or director to ensure it was in a
domain where this was safe before calling sendClear().
Hence the lack of domain polymorphism.

Specifically, FixedPointDirector was needing
to characterize the directors within which it was enclosed.
It was doing this incorrectly (forgot to think about
FSMDirector), and hence the HybridPlant model was not
working correctly.

So I've introduced an alternative mechanism where a director
writer doesn't have to reason about what domain his/her
director sits within. IOPort.send()
and IOPort.sendInside() can now accept a null token (they
would previously throw an exception). Similarly, Receiver.put()
can accept a null token.  The documentation says this:

*  If a null token is specified, this is interpreted as an assertion
*  that no token is being sent. For some domains, specifically those
*  that queue tokens such as PN and SDF, this has no effect. For
*  others, specifically those that have a well-defined notion of
*  "absent" inputs such as SR, modal, and Continuous, sending a null
*  token corresponds to asserting that the inputs of destination
*  actors will be absent in this round.

This change required touching quite a few files. I've gone
over receivers in all domains in the Ptolemy II tree to ensure
that put() and putToAll() can now accept a null token argument.
If you have a domain not in the Ptolemy II tree, you should do
the same, or else your domain will misbehave if you put inside
it an SR or Continuous model.

Edward



-------------- next part --------------
A non-text attachment was scrubbed...
Name: eal.vcf
Type: text/x-vcard
Size: 351 bytes
Desc: not available
URL: <http://mercury.nceas.ucsb.edu/kepler/pipermail/kepler-dev/attachments/20091201/291a8c9f/attachment.vcf>