ptolemy.domains.sr.kernel
Class SRReceiver

java.lang.Object
  extended byptolemy.actor.AbstractReceiver
      extended byptolemy.domains.sr.kernel.SRReceiver
All Implemented Interfaces:
Receiver

public class SRReceiver
extends AbstractReceiver

The receiver for the Synchronous Reactive (SR) domain. This receiver is a mailbox with capacity one. The status of this receiver can be known (either known to contain a token or known not to contain a token) or unknown. The isKnown() method returns true if the receiver has known status. If the receiver has known status, the hasToken() method returns whether the receiver has a token. If the receiver has unknown status, the hasToken() method will throw an UnknownTokenException.

In the course of an iteration in SR, receivers can change from unknown status to known status, but never the other way around, as shown by the transitions in the diagram below.

   known values:     absent     value (present)
   ^         ^
   |         |
   \       /
   \     /
   |   |
   unknown
   

The status is automatically set to known when the put() method or clear() method is called. Once a receiver becomes known, its value (or lack of a value if it is absent) cannot change until the next call to reset(). The SRDirector calls reset() between iterations. The hasRoom() method returns true if the state of the receiver is unknown or if it is known but not absent, since only in these circumstances can it accept a token. Attempting to change the status of a receiver from present to absent or from absent to present will result in an exception. An exception will also be thrown if a receiver has present status and it receives a token that is not the same as the one it already contains (as determined by the isEqualTo() method of the token). Thus, for an actor to be valid in SR, a firing must produce the same outputs given the same inputs (in a given iteration).

Since the value of a receiver cannot change (once it is known) in the course of an iteration, tokens need not be consumed. A receiver retains its token until the director calls the reset() method at the beginning of the next iteration, which resets the receiver to have unknown status. There is no way for an actor to reset a receiver to have unknown status.

Since:
Ptolemy II 2.0
Version:
$Id: SRReceiver.java,v 1.40 2004/04/13 21:34:19 cxh Exp $
Author:
Paul Whitaker, contributor: Christopher Hylands
See Also:
SRDirector
Accepted Rating:
Green (pwhitake)
Proposed Rating:
Green (pwhitake)

Field Summary
protected  Token _token
          The token held.
 
Constructor Summary
SRReceiver(SRDirector director)
          Construct an SRReceiver with unknown state and the given director.
 
Method Summary
 void clear()
          Set the state of this receiver to be known and to contain no token.
 Token get()
          Get the contained Token without modifying or removing it.
 boolean hasRoom()
          Return true if the state of the receiver is unknown or if it is known and not empty.
 boolean hasRoom(int numberOfTokens)
          Return what hasRoom() returns if the argument is 1, and otherwise return false.
 boolean hasToken()
          Return true if the receiver contains a token, or false otherwise.
 boolean hasToken(int numberOfTokens)
          Return what hasToken() returns if the argument is 1, and otherwise return false.
 boolean isChanged()
          Return true if this receiver changes from unknown to known.
 boolean isKnown()
          Return true if this receiver has known state, that is, the token in this receiver is known or if this receiver is known not to contain a token.
 void put(Token token)
          Set the state of this receiver to be known and to contain the specified token.
 void reset()
          Reset the receiver by removing any contained token and setting the state of this receiver to be unknown.
 
Methods inherited from class ptolemy.actor.AbstractReceiver
getArray, getContainer, getCurrentTime, putArray, setContainer
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

_token

protected Token _token
The token held.

Constructor Detail

SRReceiver

public SRReceiver(SRDirector director)
Construct an SRReceiver with unknown state and the given director.

Method Detail

clear

public void clear()
           throws IllegalActionException
Set the state of this receiver to be known and to contain no token. Note that during an iteration, SR semantics does not allow a receiver to receive a token and then be cleared. Thus, the clear will trigger an exception.

Specified by:
clear in interface Receiver
Overrides:
clear in class AbstractReceiver
Throws:
IllegalActionException - If the receiver state is known and the receiver has a token.

get

public Token get()
          throws NoTokenException
Get the contained Token without modifying or removing it. If there is none, throw an exception.

Specified by:
get in interface Receiver
Specified by:
get in class AbstractReceiver
Returns:
The token contained in the receiver.
Throws:
NoTokenException - If this mailbox is empty.

hasRoom

public boolean hasRoom()
Return true if the state of the receiver is unknown or if it is known and not empty. This is equivalent to the expression
    !isKnown() || hasToken()
  

Specified by:
hasRoom in interface Receiver
Specified by:
hasRoom in class AbstractReceiver
Returns:
True if the receiver can accept a token.

hasRoom

public boolean hasRoom(int numberOfTokens)
                throws java.lang.IllegalArgumentException
Return what hasRoom() returns if the argument is 1, and otherwise return false.

Specified by:
hasRoom in interface Receiver
Specified by:
hasRoom in class AbstractReceiver
Parameters:
numberOfTokens - The number of tokens to put into the mailbox.
Returns:
True if the next numberOfTokens calls to put() will not result in a NoRoomException.
Throws:
java.lang.IllegalArgumentException - If the argument is not positive. This is a runtime exception, so it does not need to be declared explicitly.
See Also:
hasRoom()

hasToken

public boolean hasToken()
Return true if the receiver contains a token, or false otherwise. If the receiver has unknown status, this method will throw an exception.

Specified by:
hasToken in interface Receiver
Specified by:
hasToken in class AbstractReceiver
Returns:
True if this receiver contains a token.
Throws:
UnknownTokenException - If the state is unknown.

hasToken

public boolean hasToken(int numberOfTokens)
                 throws java.lang.IllegalArgumentException
Return what hasToken() returns if the argument is 1, and otherwise return false. If the receiver has unknown status, this method will throw an UnknownTokenException, which is a RuntimeException so it need not be declared explicitly. If the argument is 0 or a negative number, then this method will throw an IllegalArgumentException, which is a RuntimeException.

Specified by:
hasToken in interface Receiver
Specified by:
hasToken in class AbstractReceiver
Parameters:
numberOfTokens - The number of tokens to get from the receiver.
Returns:
True if the argument is 1 and the receiver has a token.
Throws:
java.lang.IllegalArgumentException - If the argument is not positive. This is a runtime exception, so it does not need to be declared explicitly.
UnknownTokenException - If the state is unknown.
java.lang.IllegalArgumentException - If the state is unknown.
Since:
Ptolemy II 2.1
See Also:
hasToken()

isChanged

public boolean isChanged()
Return true if this receiver changes from unknown to known.

Returns:
True if this receiver changes from unknown to known state.

isKnown

public boolean isKnown()
Return true if this receiver has known state, that is, the token in this receiver is known or if this receiver is known not to contain a token.

Specified by:
isKnown in interface Receiver
Overrides:
isKnown in class AbstractReceiver
Returns:
True if this receiver has known state.

put

public void put(Token token)
Set the state of this receiver to be known and to contain the specified token. If the receiver already contains an equal token, do nothing.

Specified by:
put in interface Receiver
Specified by:
put in class AbstractReceiver
Parameters:
token - The token to be put into this receiver.
Throws:
java.lang.IllegalArgumentException - If the argument is null.
IllegalOutputException - If the state is known and absent, or a token is present and does not have the same value.

reset

public void reset()
Reset the receiver by removing any contained token and setting the state of this receiver to be unknown. This is called by the director between iterations.