package tezos-lwt-result-stdlib

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.

Note the Seq module (along with the Seq_* modules) (unlike other modules of Lwtreslib) uses submodules to organise different monadic traversors. This is because the implementation of the Seq module is delegated to the Seqes library which uses functors which produces (sub)modules.

All traversal functions that are inside the E submodule 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 inside the S submodule 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 inside the ES submodule 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 (S.map, E.map, 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.