The deferred analog of
Core.Or_error. It is exposed in std.ml as
The mental model for a function returning an
'a Deferred.Or_error.t is that the function never raises. All error cases are caught and expressed as an
Error _ result. This module preserves that property.
Unfortunately, there is no way to enforce this property using the type system, so it is more like a convention, or idiom. A function whose type ends with
... -> 'a
Deferred.Or_error.t and still raises should be considered broken, and be fixed. With that property in mind,
Deferred.Or_error.List.iter, for example, does not wrap the execution of the given iter function
f inside a monitor. If one of these application raises, the whole function
Deferred.Or_error.List.iter will raise as a way to try to alert the developer that the function is broken and needs attention and fixing, rather than silently catching the error and converting it to
This behavior is consistent with
Core.Or_error's treatment of user-supplied functions.
If you have to deal with a function that does not respect this idiom, you can use
Deferred.Or_error.try_with_join to wrap its execution and enforce this property.
module Deferred : sig ... end
type 'a t = 'a Core.Or_error.t Deferred.t
The applicative operations match the behavior of the applicative operations in
Or_error. This means that
all_unit are equivalent to
include Core.Applicative.S with type 'a t := 'a t
module Applicative_infix : sig ... end
return x = Deferred.return (Ok x) *
include Core.Monad.S with type 'a t := 'a t
t >>= f returns a computation that sequences the computations represented by two monad elements. The resulting computation first does
t to yield a value
v, and then runs the computation returned by
module Monad_infix : sig ... end
val return : 'a -> 'a t
return v returns the (trivial) computation that returns v.
ignore_m t is
map t ~f:(fun _ -> ()).
ignore_m used to be called
ignore, but we decided that was a bad name, because it shadowed the widely used
Caml.ignore. Some monads still do
let ignore = ignore_m for historical reasons.
all, but ensures that every monadic value in the list produces a unit value, all of which are discarded rather than being collected into a list.
module Let_syntax : sig ... end
These are convenient to have in scope when programming with a monad:
val fail : Core.Error.t -> _ t
fail error = Deferred.return (Error error) *
val ok_exn : 'a t -> 'a Deferred.t
These functions are direct analogs of the corresponding
val of_exn : exn -> _ t
val of_exn_result : ('a, exn) Core.Result.t Deferred.t -> 'a t
val error : string -> 'a -> ('a -> Core.Sexp.t) -> _ t
val error_s : Core.Sexp.t -> _ t
val error_string : string -> _ t
val errorf : ('a, unit, string, _ t) Core.format4 -> 'a
val tag_s : 'a t -> tag:Core.Sexp.t -> 'a t
val tag_s_lazy : 'a t -> tag:Core.Sexp.t Core.Lazy.t -> 'a t
val tag_arg : 'a t -> string -> 'b -> ('b -> Core.Sexp.t) -> 'a t
val unimplemented : string -> _ t
find_map_ok l ~f returns the first value in
l for which
Ok, otherwise it returns the same error as
combine_errors (Deferred.List.map l ~f).
val ok_unit : unit t
ok_unit = return ()
val try_with : ?extract_exn:bool -> ?run:[ `Now | `Schedule ] -> ?rest:[ `Log | `Raise | `Call of exn -> unit ] -> ?here:Lexing.position -> ?name:string -> (unit -> 'a Deferred.t) -> 'a t
try_with f catches exceptions thrown by
f and returns them in the Result.t as an Error.t.
try_with_join is like
try_with, except that
f can throw exceptions or return an
Error directly, without ending up with a nested error; it is equivalent to
try_with f >>| Result.join.
extract_exn is passed along to
Monitor.try_with ?extract_exn and specifies whether or not the monitor exn wrapper should be skipped (
extract_exn:true or kept (
~rest argument controls how exceptions are handled after the
try_with deferred becomes determined. They may be logged, raised, or passed to a callback.
~run argument controls when
f gets called.
`Schedule schedules an asynchronous job to run
val try_with_join : ?extract_exn:bool -> ?run:[ `Now | `Schedule ] -> ?rest:[ `Log | `Raise | `Call of exn -> unit ] -> ?here:Lexing.position -> ?name:string -> (unit -> 'a t) -> 'a t
module List : Monad_sequence.S with type 'a monad := 'a t with type 'a t := 'a list
All of the
List functions that take a
how argument treat it the following way:
val repeat_until_finished : 'state -> ('state -> [ `Repeat of 'state | `Finished of 'result ] t) -> 'result t
repeat_until_finished initial_state f works just like
Deferred.repeat_until_finished but with the
Deferred.Or_error monad. If
f returns an
Or_error.Error the loop terminates and returns.