_AN ASYNCHRONOUS DESIGN PATTERN_
by Allan Vermeulen

Listing One

/* File: IOUCallback.java */
/**
 * An object to be run when an IOU is closed.  Each Escrow has a list
 * of these objects.  They get fired when the IOU's escrow is closed.
 *
 * @see IOU, Escrow
 *
 * @author: alvis, 1/26/96
 */

package iou;

public interface IOUCallback {
  public void run(Object o);
};


Listing Two

/* File: IOU.java */
package iou;

/**
 * An IOU is a token that you can later redeem for an actual object.
 * IOUs are typically returned from functions that build their results
 * asynchronously.
 *
 * An IOU refers to an Escrow object.  The Escrow is responsible for
 * obtaining and holding on to the object referred to by the IOU.
 * 
 * @author Alvis, 2/7/96
 */

public class IOU extends Object {
  private Escrow escrow_;

  /**
   * Check if the IOU can be immediately redeemed.  If this returns
   * true, then none of IOUs member functions will block.  If it
   * returns false then standBy and redeem will likely block.
   */
  public boolean closed() {return escrow_.closed();}

  /**
   * Wait until the object is ready.  This will cause this thread of
   * execution to block.
   * @exception InterruptedException When the thread is interupted before
   *                                 the IOU is enabled.
   */
  public void standBy() throws InterruptedException {escrow_.standBy();}

  /**
   * Get the object promised by the IOU.
   * This will block if the IOU has not been enabled yet.
   * @exception InterruptedException When the thread is interupted before
   *                                 the IOU is enabled.
   */
  public Object redeem() throws InterruptedException {return escrow_.redeem();}

  /**
   * The run(Object) object interface in the IOUCallback
   * will be invoked when the IOU is enabled.  The object passed
   * as a parameter to the callback is the IOU's value.
   * The callback is normally run in the same thread in which the
   * escrow is enabled.
   * If the IOU is already enabled, then it will be run immediately.
   */
  public void addCallback(IOUCallback callback)
  {
    escrow_.addCallback(callback);
  }

  /**
   * Remove a callback that was previously added.  If the callback
   * is not on the callback list it is ignored.
   */
   public void removeCallback(IOUCallback callback)
   {
     escrow_.removeCallback(callback);
   }

  /**
   * Normally, you receive IOUs as return values from functions, you
   * don't build them yourself.  If you are giving out IOUs, you should
   * obtain them from Escrow.iou.
   */
  public IOU(Escrow e) {escrow_ = e;} 
}

 

Listing Three

/* File: Escrow.java */
package iou;

/**
 * Escrow mediates the transaction between someone with an IOU, and
 * the party that gave out the IOU.  Before you can give out an
 * IOU, you must create an Escrow.  The IOU will refer to the Escrow
 * for all of its functionality.  You must (eventually) enable the 
 * Escrow before any IOU which refer to this Escrow can be redeemed.
 *
 * This is an abstract base class.  The mechanism used to wait until
 * the Escrow is enabled is implemented by overriding the function
 * block().  The default mechanism for holding the object is to
 * keep a copy in a variable in the Escrow.  It is expected that
 * some subclasses will override enabled(), value(), enable(), and
 * block() to change this policy.
 *
 * @see IOU
 * @author Alvis, 1/25/96 and 3/19/96
 */

public abstract class Escrow extends Object {
  private boolean          closed_;     //can IOUs be redeemed without blocking?
  private java.util.Vector callbackList;//fire when ready

  /**
   * Constructor.
   */
  public Escrow()
  {
    closed_ = false;
    callbackList = new java.util.Vector();
  }

  /**
   * Return an IOU which refers to this Escrow.
   * The normal method of using an Escrow is to create the Escrow, and
   * then use this method to give out IOUs.
   */
  public IOU iou()  {return new IOU(this);}

  /**
   * Close the IOU.  Once this is called, then redeem() and standBy()
   * must return without blocking.
   * Closing the IOU will run any callbacks which have been queued up.
   * Closing escrow more than once has no effect.
   * There can only be one first time.
   */
  synchronized protected void close()
  {
    closed_ = true;
    Object value = redeemAfterClose();
    // Fire the callbacks in the order they were provided.
    // The callback list has no elements if we have already closed escrow.
    for(int i=0; i<callbackList.size(); i++) {
      IOUCallback callback = (IOUCallback)callbackList.elementAt(i);
      callback.run(value);
    }
    callbackList.removeAllElements();
  }

  /**
   * Wait until the escrow is closed.
   * This is normally called by an IOU to wait until a supplier
   * closes escrow.
   * I'd have liked to call this function wait, but that name
   * has been usurped by the Object class.
   * @exception InterruptedException When the thread is interupted before
   *                                 the escrow is closed.
   */
  abstract public void standBy() throws InterruptedException;

  /**
   * Return the object held in escrow, blocking if necessary.
   * This is called by IOU.redeem().
   * If the escrow is not yet closed, this will block until it
   * is closed.
   * @exception InterruptedException When the thread is interupted before
   *                                 the IOU is enabled.
   */
  abstract public Object redeem() throws InterruptedException;

  /**
   * Return object in escrow without ever throwing an exception.
   * This method does the same thing as redeem, only it throws
   * an error rather than an exception if the redeem is interrupted.
   * It is intended for use after the escrow is known to be closed,
   * to avoid worrying about what to do with InterruptedException when
   * you know they won't be thrown.
   */
  private Object redeemAfterClose()
  {
    Object value;
    try {
      value = redeem();
    }
    catch(InterruptedException e) {
      throw new Error("logic error in Escrow");
    }
    return value;
  }

  /**
   * Returns true if the Escrow is enabled, false otherwise.
   * Its ok for this not to be
   * synchronized.  At worst, it will provide a false negative
   * if the object is being set as this is being executed.
   */
  public boolean closed() {return closed_;}

  /**
   * This adds to the list of callbacks.  If escrow has
   * already been closed, then it just fires the callback
   * now.
   */
  public synchronized void addCallback(IOUCallback f)
  {
    if (closed()) {
      Object value = redeemAfterClose();
      f.run(value);
    } else {
      callbackList.addElement(f);
    }
  }

  /**
   * Remove a callback.
   * If there is more than once instance of this callback, this removes
   * the first one of them added.
   * If there is no such callback, this code just quietly does nothing.
   * I suppose it should really throw an exception, but adding that seems
   * too much like work.
   */
  public synchronized void removeCallback(IOUCallback f)
  {
    callbackList.removeElement(f);  // ignore error if no such element
  }
}



Listing Four

/* File: ThreadEscrow.java */
package iou;

/**
 * A framework for building IOUs by putting the supplier in its own thread.
 *
 * A ThreadEscrow computes its value in a thread that it controls.
 * You pass the escrow an ObjectMaker when you construct it.
 * ObjectMaker is a simple interface; it requires a run function which
 * builds up the object.
 * The Escrow builds a thread and runs the ObjectMaker in that thread.
 * When the ObjectMaker returns, its value is put in Escrow and the
 * thread exits.
 * 
 * The thread uses a ThreadEscrowWorker class as its Runnable object.
 * The ThreadEscrowWorker knows about the Escrow, and can therefore
 * stuff the object produced by the ObjectMaker into the Escrow.
 *
 * The standBy() function needs to wait for the thread that was launched
 * in the constructor.  This should be possible using Thread.join(),
 * but unfortunately Netscape has a bug where Thread.join() blocks
 * forever (it has been reported, see
 * http://www.roguewave.com/~alv/javaThreadBug.html for an example).
 * To get around this, the ThreadEscrowWorker has a waitForRunToFinish()
 * function.
 *
 * @author: Alvis, 1/26/96
 */

public class ThreadEscrow extends Escrow {
  private Thread              thread_;   // started in the constructor
  private ThreadEscrowWorker  worker_;   // the Runnable action in the thread
  Object                      value_;    // at closing, the value is set here

  /**
   * Start up a new thread to supply the object.  Once the
   * object is supplied, the new thread will set value_ and
   * close escrow.
   */
  public ThreadEscrow(ObjectMaker maker)
  {
    worker_ = new ThreadEscrowWorker(this,maker);
    thread_ = new Thread(worker_);
    thread_.start();
  }

  /**
   * Waits until the worker thread has completed.  When the thread 
   * has completed it will set value_.
   */
  public void standBy() throws InterruptedException
  {
    // thread_.join(); - doesn't work due to Netscape bug - see top of file
    worker_.waitForRunToFinish();
    if (!worker_.isFinished()) {
      throw new InterruptedException();
    }
  }

  /**
   * Redeem the object.  If necessary, this will wait for the thread to
   * finish computing the object.
   */
  public Object redeem() throws InterruptedException
  {
    standBy();     // if value_ is already set, this comes back fast
    return value_;
  }
}

/**
 * Do the work of supplying an object to a ThreadEscrow.
 *
 * This class manages a thread which runs the function which supplies
 * the object to the ThreadEscrow.  It should only be created by
 * a ThreadEscrow.
 */

class ThreadEscrowWorker extends Thread {
  ThreadEscrow   escrow_;       // my creator
  ObjectMaker    maker_;        // what I'm supposed to do
  boolean        runFinished_;  // has run finished executing?

  ThreadEscrowWorker(ThreadEscrow e, ObjectMaker m)
  {
    maker_ = m;
    escrow_ = e;
    runFinished_ = false;
  }

  public boolean isFinished() {return runFinished_;}
  
  public synchronized void run()
  {
    Object value = maker_.run();
    escrow_.value_ = value;
    runFinished_ = true;
    escrow_.close();
    notify();        // threads may be waiting in waitForRunToFinish()   
  }

  synchronized void waitForRunToFinish()
  {
    while (isFinished()==false) {
      try {
        wait();    // run() will call notify
      }
      catch(InterruptedException e) {}
    }
    notify();      // There may be other threads waiting in waitForRunToFinish()
  }
}  
  

Listing Five

/* File: ObjectMaker.java */
/**
 * A simple interface for objects that produce an object.
 *
 * @author: Alvis, 1/26/96
 */

package iou;

public interface ObjectMaker {
  public Object run();
}



Example 1:

// john, paul, george, ringo are Messenger objects
Dossier d1 = john.getDossier();
Dossier d2 = paul. getDossier();
Dossier d3 = george. getDossier();
Dossier d4 = ringo. getDossier();
int l = d1.length()+d2.length()+d3.length()+d4.length();

Example 2:

IOU iou1 = john. getDossierIOU();      // First get IOUs
IOU iou2 = paul. getDossierIOU();
IOU iou3 = george. getDossierIOU();
IOU iou4 = ringo. getDossierIOU();
Dossier d1 = (Dossier)iou1.redeem();  // Redeem the IOUs
Dossier d2 = (Dossier)iou2.redeem();
Dossier d3 = (Dossier)iou3.redeem();
Dossier d4 = (Dossier)iou4.redeem();
int l = d1.length()+d2.length()+d3.length()+d4.length();


Example 3:

// display1 et al are screen display panels
Dossier d1 = john.getDossier();
display1.show(d1.cover);
Dossier d2 = paul. getDossier();
display2.show(d2.cover);
Dossier d3 = george. getDossier();
display3.show(d3.cover);
Dossier d4 = ringo. getDossier();
display4.show(d4.cover)


Example 4:

// display1 et al satisfy IOUCallback interface,
// so display1.run(dossier) draws the Dossier on
// the screen
IOU iou1 = john.getDossierIOU();
iou1.addCallback(display1);
IOU iou2 = paul. getDossierIOU();
iou2.addCallback(display2);
IOU iou3 = george. getDossierIOU();
iou3.addCallback(display3);
IOU iou4 = ringo. getDossierIOU();
iou4.addCallback(display4);