An immutable sequence of values, with a possibly incomplete tail that may be extended asynchronously.
For most applications one should use Pipe instead of Stream. One justifiable usage
of Stream
rather than Pipe
is in single-writer, multi-consumer (multicast)
scenarios where pushback is not required.
The basic primitive operation for getting the next element out of stream is
Stream.next
, which (asynchronously) returns the element and the rest of the
stream.
sexp_of_t t f
returns a sexp of all of the elements currently available in the
stream. It is just for display purposes. There is no t_of_sexp
.
next t
returns a deferred that will become determined when the next part of the
stream is determined. This is Cons (v, t')
, where v is the next element of the
stream and t' is the rest of the stream, or with Nil at the end of the stream.
Streams can be converted to and from lists. Although, conversion to a list returns a deferred, because the stream is determined asynchronously.
of_list l
returns a stream with the elements of list l.
to_list t
returns a deferred that will become determined with the list
of elements in t, if the end of t is reached.
Sequence operations ---------------------------------------------------------------------- There are the usual sequence operations:
append, fold, iter, map, filter_map, take
There are also deferred variants:
iter', map', filter_map'
These take anonymous functions that return deferreds generalizing the usual sequence operation and allowing the client to control the rate at which the sequence is processed.
fold' t ~init ~f
is like list fold, walking over the elements of the stream in
order, as they become available. fold'
returns a deferred that will yield the final
value of the accumulator, if the end of the stream is reached.
iter' t ~f
applies f
to each element of the stream in turn, as they become
available. It continues onto the next element only after the deferred returned by f
becomes determined.
iter t ~f
= don't_wait_for (iter' t ~f:(fun a -> f a; Deferred.unit))
iter_durably' t ~f
is like iter' t ~f
, except if f
raises an exception it
continues with the next element of the stream *and* reraises the exception (to the
monitor in scope when iter_durably was called).
iter_durably t ~f
is like iter t ~f
, except if f
raises an exception it
continues with the next element of the stream *and* reraises the exception (to the
monitor in scope when iter_durably was called).
iter_durably_report_end t ~f
is equivalent to iter_durably' t ~f:(fun x -> return
(f x))
but it is more efficient
length s
returns a deferred that is determined when the end of s is reached, taking
the value of the number of elements in s
Stream generation ----------------------------------------------------------------------
unfold b f
returns a stream a1; a2; ...; an
whose elements are
determined by the equations:
b0 = b Some (a1, b1) = f b0 Some (a2, b2) = f b1 ... None = f bn
Miscellaneous operations ----------------------------------------------------------------------
split ~stop ~f t
returns a pair (p, d)
, where p
is a prefix of t
that ends
for one of three reasons:
1. [t] ends 2. stop becomes determined 3. f returns `Found
The deferred d
describes why the prefix ended, and returns the suffix of the
stream in case (2) or (3).
find ~f t
returns a deferred that becomes determined when f x
is true for some
element of t
, or if the end of the stream is reached