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.