** What is the 'deferred pattern'?

The deferred pattern, described in
http://wiki.ecmascript.org/doku.php?id=strawman:deferred_functions#de...,
allows you to wait for an asynchronous operation from plain
JavaScript.
A deferred function is a function that does something asynchronous
under the hood, but returns an object with two member functions:

  then: function(callback, errback)
  cancel: function()

You would use it like this:

  some_asynchronous_function().then(callback, errback);

Once some_asynchronous_function is finished, it calls callback (or
errback, as appropriate).

** Why would you want this for StratifiedJS?

The rationale for implementing something like this for StratifiedJS,
is so that we can call an asynchronous StratifiedJS function from
plain JS and get our plain JS to wait for its result.
(Remember that it is already possible to call any SJS function from
plain JS - but if the SJS function does something asynchronous then it
will immediately return with an unintelligible return value - see also
http://onilabs.com/docs#patterns ).

** Implementation

As it turns out, we can implement something like the deferred pattern
in 'userspace' StratifiedJS - it doesn't require any new SJS runtime
support.

Here is a higher-order SJS function that makes a deferred function out
of any function f:

  function makeDeferredFunction(f) {
    return function() {
      var stratum = spawn f.apply(this, arguments);
      var deferred = {
        then : function(callback, errback) {
          spawn (function() {
            try { callback(stratum.waitforValue()); }
            catch (e) { if (errback) errback(e); }
          })();
          return deferred;
        },
        cancel : function() {
          stratum.abort();
        }
      };
      return deferred;
    }
  };

I've checked this function into the 'cutil' module on our github trunk
for now, see https://github.com/onilabs/apollo/blob/master/modules/cutil.sjs#L340
. Note that the module library is due for a bit of an overhaul, so it
might end up elsewhere in future.

** How to use it

Take any SJS function, e.g.:

  function wait(t) {
    hold(t);
    return 'we waited '+t/1000+'seconds';
  }

You can make a deferred version out of it like this:

  var deferred_wait = require('apollo:cutil').makeDeferredFunction(wait);

Now you can call wait() from plain JS like this:

  wait(1000).then(function(x) { alert(x); });

In the same way you can make deferred versions out of any of the
existing apollo library function:

E.g. for http.get (see
http://code.onilabs.com/apollo/unstable/doc/modules.html#http/get ):

Now you can call deferred_wait() from plain JS like this: