Prophecy

_Prophecy_
_prophecy_

This collection provides one file:

 _prophecy.ss_: a "future-generator" control construct.

======================================================================

DATA DEFINITIONS -----------------------------------------------------

A (prophecyof a) is an opaque data structure representing a prophecy
whose yielded values are of type a.

A (streamof a) is one of:

  - (promiseof null)
  - (promiseof (cons a (streamof a)))

CONSTANTS ------------------------------------------------------------

> stop-iteration

A special sentinel value raised by `prophecy-next' when the prophecy
is complete.

PROCEDURES -----------------------------------------------------------

> (prophecy? v) :: any -> boolean

Determines whether the argument is a prophecy.

> (yield v) :: a -> any

Adds the given value to the prophecy's internal queue and returns
immediately. It is an error to invoke `yield' outside the context of a
prophecy.

Note that a well-typed invocation of `yield' is applied to an argument
of type a when invoked in the context of a prophecy of type
(prophecyof a).

> (prophecy-next p) :: (prophecyof a) -> a

Takes a prophecy and returns the next yielded value in its internal
queue, blocking until such a value exists. If the prophecy is
complete, this procedure raises the special value `stop-iteration'.

> (prophecy->stream p) :: (prophecyof a) -> (streamof a)

Produces a lazy stream of the yielded values in a prophecy's interanl
queue.

SYNTAX ---------------------------------------------------------------

> (prophecy e0 e1 ...) :: SYNTAX

The `prophecy' form takes one or more subexpressions and evaluates
them sequentially in a separate thread. Within the current thread, the
form immediately evaluates to a `prophecy' data structure.

TODO:

- prophecy-complete? :: prophecy -> boolean
- yield should probably be a syntax, not a function
  (we can't currently prevent all erroneous uses of it)