ptolemy.domains.de.kernel
Class DEReceiver

java.lang.Object
  extended byptolemy.actor.AbstractReceiver
      extended byptolemy.domains.de.kernel.DEReceiver
All Implemented Interfaces:
ptolemy.actor.Receiver
Direct Known Subclasses:
WirelessReceiver

public class DEReceiver
extends ptolemy.actor.AbstractReceiver

An implementation of the ptolemy.actor.Receiver interface for the DE domain. Tokens that are put into this receiver logically have time stamps. If the time stamp is not explicitly given using the setDelay() method, then it is assumed to be the current time (which is maintained by the director). The put() method sends the specified token to the director, which returns it to this receiver (via the protected method _triggerEvent()) when current time matches the time stamp of the token. The get() method returns only tokens that the director has so returned. Thus, when a token is put into the receiver using put(), it does not become immediately available to the get() method.

By default, the time stamp of a token is the current time of the director when put() is called. To specify a time stamp in the future, call setDelay() prior to calling put(). This should be done in a synchronized manner, since there could be multiple thread running in this domain.

Before firing an actor, the director is expected to put at least one token into at least one of the receivers contained by the actor.

Since:
Ptolemy II 0.2
Version:
$Id: DEReceiver.java,v 1.72 2004/04/13 05:12:45 cxh Exp $
Author:
Lukito Muliadi, Edward A. Lee, Jie Liu
Accepted Rating:
Green (cxh)
Proposed Rating:
Green (liuj)

Constructor Summary
DEReceiver()
          Construct an empty DEReceiver with no container.
DEReceiver(ptolemy.actor.IOPort container)
          Construct an empty DEReceiver with the specified container.
 
Method Summary
protected  void _triggerEvent(ptolemy.data.Token token)
          Make a token available to the get() method.
 void clear()
          Clear this receiver of any contained tokens.
 ptolemy.data.Token get()
          Get a token from the receiver.
 DEDirector getDirector()
          Return the director that created this receiver.
 boolean hasRoom()
          Return true, indicating that there is always room.
 boolean hasRoom(int tokens)
          Return true if the receiver has room for putting the given number of tokens into it (via the put() method).
 boolean hasToken()
          Return true if there are tokens available to the get() method.
 boolean hasToken(int numberOfTokens)
          Return true if there are numberOfTokens tokens tokens available to the get() method.
 void put(ptolemy.data.Token token)
          Put a token into this receiver.
 void put(ptolemy.data.Token token, double time)
          Put a token into this receiver with a future time stamp.
 void setDelay(double delay)
          Set the delay for the next call to put().
 
Methods inherited from class ptolemy.actor.AbstractReceiver
getArray, getContainer, getCurrentTime, isKnown, putArray, setContainer
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DEReceiver

public DEReceiver()
Construct an empty DEReceiver with no container.


DEReceiver

public DEReceiver(ptolemy.actor.IOPort container)
           throws ptolemy.kernel.util.IllegalActionException
Construct an empty DEReceiver with the specified container.

Parameters:
container - The container.
Throws:
ptolemy.kernel.util.IllegalActionException - If the container does not accept this receiver.
Method Detail

clear

public void clear()
Clear this receiver of any contained tokens.


get

public ptolemy.data.Token get()
                       throws ptolemy.actor.NoTokenException
Get a token from the receiver. The token returned is one that was put in the receiver with a time stamp equal to or earlier than the current time. Note that there might be multiple such tokens in the receiver. In that case, FIFO behaviour is used with respect to the put() method. If there is no such token, throw an exception. This method is synchronized since the actor may not execute in the same thread as the director.

Returns:
A token.
Throws:
ptolemy.actor.NoTokenException - If there are no more tokens. This is a runtime exception, so it need not be declared explicitly.

getDirector

public DEDirector getDirector()
                       throws ptolemy.kernel.util.IllegalActionException
Return the director that created this receiver. If this receiver is an inside receiver of an output port of an opaque composite actor, then the director will be the local director of the container of its port. Otherwise, it's the executive director of the container of its port.Note that the director returned is guaranteed to be non-null. This method is read synchronized on the workspace.

Returns:
An instance of DEDirector.
Throws:
ptolemy.kernel.util.IllegalActionException - If there is no container port, or if the port has no container actor, or if the actor has no director, or if the director is not an instance of DEDirector.

hasRoom

public final boolean hasRoom()
Return true, indicating that there is always room.

Returns:
True.

hasRoom

public boolean hasRoom(int tokens)
Return true if the receiver has room for putting the given number of tokens into it (via the put() method). Returning true in this method should also guarantee that calling the put() method will not result in an exception.


hasToken

public boolean hasToken()
Return true if there are tokens available to the get() method.

Returns:
True if there are more tokens.

hasToken

public boolean hasToken(int numberOfTokens)
Return true if there are numberOfTokens tokens tokens available to the get() method.

Returns:
True if there are numberOfTokens tokens available.

put

public void put(ptolemy.data.Token token)
Put a token into this receiver. Note that this token does not become immediately available to the get() method. Instead, the token is queued with the director, and the director must put the token back into this receiver using the _triggerEvent() protected method in order for the token to become available to the get() method. By default, this token will be enqueued by the director with the current time of the director. However, by calling setDelay() before calling put(), you can enqueue the event with a time stamp at a future time. This method is synchronized since the actor may not execute in the same thread as the director.

Parameters:
token - The token to be put.

put

public void put(ptolemy.data.Token token,
                double time)
         throws ptolemy.kernel.util.IllegalActionException
Put a token into this receiver with a future time stamp. This token will be available to the get() method at the time specified. Note that the time should be greater than or equal to the current time of the director, otherwise an exception will be thrown. This method is synchronized since the actor may not execute in the same thread as the director.

Parameters:
token - The token to be put.
time - The time stamp of the token
Throws:
ptolemy.kernel.util.IllegalActionException - If time is less than the current time of the director, or no director is available.

setDelay

public void setDelay(double delay)
              throws ptolemy.kernel.util.IllegalActionException
Set the delay for the next call to put(). This causes the director to make the token available for the get() method at some future time, i.e. current time plus the specified delay. This value of delay is only used in the next call to put(). If the specified delay is zero, then the next event is queued to be processed in the next microstep. This method is synchronized since the actor may not execute in the same thread as the director.

Parameters:
delay - The delay.
Throws:
ptolemy.kernel.util.IllegalActionException - If the delay is negative.

_triggerEvent

protected void _triggerEvent(ptolemy.data.Token token)
Make a token available to the get() method. Normally, only a director will call this method. It calls it when current time matches the time stamp of the token, i.e. when the delay specified by setDelay() has elapsed.

Parameters:
token - The token to make available to get().