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

[Edward A. Lee]

Good question.  Sending null doesn't mean receiving null.
See if this documentation for the send() method makes it clear
(if not, we need to improve this):

In TypedIOPort:

     /** Send a token to the specified channel, checking the type
      *  and converting the token if necessary.
      *  ...
      *  <p>
      *  If the token argument is null, then no token is sent.
      *  What this means exactly is domain dependent. In some domains
      *  (SR, Continuous), it asserts that the output is "absent."
      *  That is, {@link #isKnown(int)} will return true
      *  and {@link #hasToken(int)} will return false.
      *  In other domains (SDF, DE, PN), it simply does nothing.
      *  Nothing is sent. Hence, {@link #isKnown(int)}
      *  and {@link #hasToken(int)} will return whatever they would
      *  have returned before the call.
      *  <p>
      *  ...
      */
     public void send(int channelIndex, Token token)
             throws IllegalActionException, NoRoomException {
         ...
     }

Edward



Jia Zou wrote:
> Hi Edward,
> The get() method of IOPort has this:
>         if (token == null) {
>             throw new NoTokenException(this, "No token to return.");
>         }
> 
> If you are allowed to send a null token, then should this not be there 
> anymore?
> 
> Jia
> 
> On Tue, Dec 1, 2009 at 9:55 AM, Edward A. Lee <eal at eecs.berkeley.edu 
> <mailto:eal at eecs.berkeley.edu>> wrote:
> 
> 
>     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
> 
> 
> 
> 
> 
>     This message is sent via the ptolemy-hackers mailing list, see
>     https://lists.eecs.berkeley.edu/sympa/info/ptolemy-hackers
> 
> 
-------------- 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/7a98874a/attachment.vcf>