Module Bare_sigs.SeqSource

Seq

A replacement for Stdlib.Seq which

• is exception-safe,
• includes Lwt-, result- and Lwt-result-aware traversal functions.

See Lwtreslib for a general description of traversors and the meaning for the name suffixes. A full description is also below.

All traversal functions that are suffixed with _e are within the result monad. Note that these functions have a "fail-early" behaviour: the traversal is interrupted as soon as any of the intermediate application fails (i.e., returns an Error _).

All traversal functions that are suffixed with _s are within the Lwt monad. These functions traverse the elements sequentially: the promise for a given step of the traversal is only initiated when the promise for the previous step is resolved. Note that these functions have a fail-early behaviour: the traversal is interrupted if any of the intermediate promise is rejected.

All the traversal functions that are suffixed with _p are within Lwt. These functions traverse the elements concurrently: the promise for all the steps are created immediately. The suffix _p is chosen for similarity with the Lwt_list functions even though, as with Lwt_list's functions there is no parallelism involved, only concurrency. Note that these functions have a “best-effort” behaviour: the whole-traversal promise (i.e., the promise returned by the _p-suffixed function) only resolves once each of the step promises have resolved. Even if one of the step promise is rejected, the whole-traversal promise is only rejected once all the other step promises have resolved.

All the traversal functions that are suffixed with _es are within the combined error-and-Lwt monad. These function traverse the elements sequentially with a fail-early behaviour for both rejection (as an Lwt promise) and failure (as a result).

All the traversal functions that are suffixed with _ep are within the combined error-and-Lwt monad. These function traverse the elements concurrently with a best-effort behaviour.

Special consideration

Because of the type of Stdlib.Seq.t, some interactions with Lwt are not possible. Specifically, note that the type includes the variant unit -> 'a node which is not within Lwt nor within the result monad. As a result, some of the traversals (map_s, map_e, etc.) cannot be applied lazily.

Check-out the S variants (Seq_s.S, Seq_e.S, and Seq_es.S) that integrate the base sequence type better with the monads' type. It is recommended that you use the variant as appropriate to your traversal. Note the presence of of_seq in each of those variants to convert from the standard S.t.