ostore.util
Class AckStage

java.lang.Object
  |
  +--ostore.util.StandardStage
        |
        +--ostore.util.AckStage
All Implemented Interfaces:
EventHandlerIF
Direct Known Subclasses:
DynamicTClient

public abstract class AckStage
extends StandardStage
implements EventHandlerIF

The AckStage is a general tool for adding robustness to NetworkMessages. If a stage wants reliable delivery of messages, they need only extend this stage, have their reliable messages extend AckStage.GenericNonceMsg, and use sendNonceMsg(ostore.util.NonceMsg, long, java.lang.Object) to dispatch the messages. The stage is smart in that it will piggyback acks onto messages already heading to a node.

This can also be used to ack end-to-end messages such as TapestryRouteMsgs, by using the methods forceRegisterNonce(long, java.lang.Object) and forceSendAck(ostore.util.NodeId, int, short). For normal NetworkMessages that extend NonceMsg, everything is taken care of automatically.

If a reliable message times out, the AckStage will call back to the child stage through the timeoutCallback(ostore.util.NonceMsg, java.lang.Object) method. This must be implemented by each child stage separately.

Note that stages extending this should NOT implement handleEvents and handleEvent. Instead, they should implement the method handle_event(seda.sandStorm.api.QueueElementIF). Along with all the normal events to expect to be passed into this method, the stage should also expect NonceAckMsg and Signal.AlarmSignal, but probably will not want to act on them; they are taken care of by the parent's method, handle_event(seda.sandStorm.api.QueueElementIF), which should be called at the top of the child's handle_event as: super.handle_event(event).

Version:
$Id: AckStage.java,v 1.5 2003/03/27 20:59:42 strib Exp $
Author:
Jeremy Stribling

Inner Class Summary
protected  class AckStage.GenericNonceMsg
           
protected  class AckStage.NonceNotFoundException
           
 
Field Summary
protected  short my_stage_id
           
protected  int next_nonce
           
protected  Resender resender
           
protected  LinkedList waiting_acks
           
protected  LinkedList waiting_msgs
           
 
Fields inherited from class ostore.util.StandardStage
classifier, DEBUG, event_types, inb_msg_types, my_node_id, my_sink, outb_msg_types, tag
 
Constructor Summary
AckStage()
           
 
Method Summary
 void destroy()
           
protected  int findAssociatedNonce(Object userData)
          Returns the currently un-acked nonce that was associated with the given userData.
protected  int forceRegisterNonce(long timeout, Object userData)
          Keep a record of a non-NonceMsg message.
protected  void forceSendAck(NodeId peer, int nonce, short stage_id)
          Send an ack for a non-NonceMsg message.
protected  void handle_event(QueueElementIF element)
          Handles a single event with no extra processing.
protected  void handleAlarmSignal()
          Received a resender timeout event
 void handleEvent(QueueElementIF element)
           
 void handleEvents(QueueElementIF[] element_array)
           
 void init(ConfigDataIF config)
          Sets the stage id, the initial nonce, and register for events that the stage cares about, such as NonceAckMsg and Signal.AlarmSignal.
protected  void postprocessAcks()
           
protected  void preprocessAcks()
           
protected  void receivedAck(NonceAckMsg msg)
          Got an ack.
protected  void sendNonceAckMsg(NonceAckMsg msg)
          Send a NonceAckMsg (for which you don't want an ack).
protected  void sendNonceMsg(NonceMsg msg, long timeout, Object userData)
          Send a reliable NetworkMessage.
protected abstract  void timeoutCallback(NonceMsg msg, Object userData)
          Application level timeout.
 
Methods inherited from class ostore.util.StandardStage
BUG, dispatch, now_ms
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

my_stage_id

protected short my_stage_id

resender

protected Resender resender

next_nonce

protected int next_nonce

waiting_msgs

protected LinkedList waiting_msgs

waiting_acks

protected LinkedList waiting_acks
Constructor Detail

AckStage

public AckStage()
Method Detail

init

public void init(ConfigDataIF config)
          throws Exception
Sets the stage id, the initial nonce, and register for events that the stage cares about, such as NonceAckMsg and Signal.AlarmSignal.
Specified by:
init in interface EventHandlerIF
Overrides:
init in class StandardStage

destroy

public void destroy()
Specified by:
destroy in interface EventHandlerIF
Overrides:
destroy in class StandardStage

handleEvents

public void handleEvents(QueueElementIF[] element_array)
                  throws EventHandlerException
Specified by:
handleEvents in interface EventHandlerIF
Overrides:
handleEvents in class StandardStage

handleEvent

public void handleEvent(QueueElementIF element)
                 throws EventHandlerException
Specified by:
handleEvent in interface EventHandlerIF

handle_event

protected void handle_event(QueueElementIF element)
                     throws EventHandlerException
Handles a single event with no extra processing. Needs to be overloaded by each child class, but should be called as super.handle_event(element) at the top of the overloaded method.

handleAlarmSignal

protected void handleAlarmSignal()
Received a resender timeout event

timeoutCallback

protected abstract void timeoutCallback(NonceMsg msg,
                                        Object userData)
Application level timeout. Must be overloaded by the child class.
Parameters:
msg - the msg that was never acked
userData - the data passed into sendNonceMsg(ostore.util.NonceMsg, long, java.lang.Object)

preprocessAcks

protected void preprocessAcks()

postprocessAcks

protected void postprocessAcks()

findAssociatedNonce

protected int findAssociatedNonce(Object userData)
                           throws AckStage.NonceNotFoundException
Returns the currently un-acked nonce that was associated with the given userData. This association was created through a call to either sendNonceMsg(ostore.util.NonceMsg, long, java.lang.Object) or forceRegisterNonce(long, java.lang.Object).

NOTE: This is a very slow method (involves a linear search over all currently un-acked nonces), so it should not be used if speed is of the essence. Also, if more than one nonce is associated with the given userData, it will only return the first one found.

sendNonceMsg

protected void sendNonceMsg(NonceMsg msg,
                            long timeout,
                            Object userData)
Send a reliable NetworkMessage.
Parameters:
msg - the message to send
timeout - how long to wait for a response
userData - an arbitrary object that will be passed back on a timeout

sendNonceAckMsg

protected void sendNonceAckMsg(NonceAckMsg msg)
Send a NonceAckMsg (for which you don't want an ack). Allows acks for other messages to piggy back. This is best used for messages that are already acting as application-level acks for NonceMsgs, but don't themselves require a nonce.

forceRegisterNonce

protected int forceRegisterNonce(long timeout,
                                 Object userData)
Keep a record of a non-NonceMsg message. This can be used for end-to-end acks on things like RouteMsgs. This does not actaully send any messages.
Parameters:
timeout - how long to wait for a response
userData - an arbitrary object that will be passed back on a timeout
Returns:
the nonce assigned to this message

forceSendAck

protected void forceSendAck(NodeId peer,
                            int nonce,
                            short stage_id)
Send an ack for a non-NonceMsg message. This can be used for end-to-end acks on things like RouteMsgs, if the nonce is included in the original message
Parameters:
peer - to whom to send an ack
nonce - the nonce to ack

receivedAck

protected void receivedAck(NonceAckMsg msg)
Got an ack.