ref_send API 2.17
defensive programming in Java

Package org.ref_send.promise

A promise interface.

See:
          Description

Interface Summary
Promise<T> A promise for a referent.
Receiver<T> A notification receiver.
Resolver<T> A Promise resolver.
 

Class Summary
Deferred<T> A return from an explicit promise creation.
Do<P,R> An eventual conditional code block.
Eventual The eventual operator.
Log A log interface.
Vat<T> A return from a vat creation.
 

Exception Summary
Failure Indicates a failed HTTP request.
NotAMaker Indicates the class provided to spawn is not a Maker.
Unresolved Signals a call to an unresolved promise.
 

Package org.ref_send.promise Description

A promise interface.

The ref_send API provides a language for expressing eventual control flow, where operations are only scheduled to happen later, instead of being executed immediately, as is the case with the normal flow of control in Java. To support eventual control flow, the ref_send API uses a different kind of reference, called a promise. A promise is a reference to an object which has yet to be determined. It's this flexibility that enables coding of an algorithm that manipulates values which won't be calculated until later, as is done in eventual control flow.

One way to think about promises is as a generalization of floating point numbers. Floating point arithmetic has a special way of dealing with error conditions, different from that used in integer arithmetic. For example, the expression "0 / 0" will throw an ArithmeticException, which aborts the current flow of control. In contrast, the expression "0.0 / 0.0" does not throw an exception, instead returning a special value called a NaN and allowing the current flow of control to continue.

Like a floating point number, a promise can represent either a normal value or an error condition. A fulfilled promise is a wrapper containing a normal Java reference. A rejected promise is a wrapper containing an Exception specifying the details of the error condition. For example:

 import static org.ref_send.promise.Eventual.ref;
 …

     private int balance;
     …

     public Promise<Integer>
     getBalance() { return ref(balance); }
     …
 

The static ref() function takes a normal Java reference and returns a corresponding Promise.

In floating point arithmetic, the NaN value is contagious, meaning that any other expression that uses it also returns NaN. For example, the expression "0.0 / 0.0 + 1.0" also returns NaN. An algorithm that uses floating point numbers can thus be coded such that it always runs to completion and the error condition is propagated through to the return value. A rejected promise can be used in a similar way. For example:

 public interface
 Account {
     public Promise<Integer>
     getBalance();
 }

 public class
 Customer {
     …

     public Account
     getSavings() {
         if (frozen) { throw new Frozen(); }
         return savings;
     }
 }

 …
     final Eventual _ = …
     final Customer client_ = _._(client);
     final Promise<Integer> current = client_.getSavings().getBalance();
     …
 

In the above code, the current balance will be a rejected promise, with reason Frozen, if the customer's savings account has been frozen by the bank. The rejected promise was originally produced by the getSavings() call, but propagated through the getBalance() invocation to the current balance.

In addition to representing a normal or error condition, a promise is most useful for representing a value which is yet to be determined. Such a promise may be used to refer to a value which will be calculated later, based on inputs which are not yet known. The Eventual class supports creating this kind of unresolved promise, as well as doing conditional operations on promises.


ref_send API 2.17
defensive programming in Java

Submit a bug or feature, or get help

Copyright 1998-2009 Waterken Inc. under the terms of the MIT X license.