Module Async_kernel__.Deferred_or_error

The deferred analog of Core.Or_error. It is exposed in std.ml as Deferred.Or_error.

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 one the function is broken and needs attention and fixing, rather than silently catching the error and converting it to Or_error.Error.

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 = Async_kernel__.Deferred1
type 'a t = 'a Core_kernel.Or_error.t Deferred.t

The applicative operations match the behavior of the applicative operations in Or_error. This means that all and all_unit are equivalent to combine_errors and combine_errors_unit respectively.

include Core_kernel.Applicative.S with type t := a t
type 'a t
val return : 'a ‑> 'a t
val apply : ('a ‑> 'b) t ‑> 'a t ‑> 'b t
val map : 'a t ‑> f:('a ‑> 'b) ‑> 'b t
val map2 : 'a t ‑> 'b t ‑> f:('a ‑> 'b ‑> 'c) ‑> 'c t
val map3 : 'a t ‑> 'b t ‑> 'c t ‑> f:('a ‑> 'b ‑> 'c ‑> 'd) ‑> 'd t
val all : 'a t list ‑> 'a list t
val all_unit : unit t list ‑> unit t
val all_ignore : unit t list ‑> unit t
  • Deprecated [since 2018-02] Use [all_unit]
val both : 'a t ‑> 'b t ‑> ('a * 'b) t
module Applicative_infix : sig ... end
include module type of Applicative_infix
val (<*>) : ('a ‑> 'b) t ‑> 'a t ‑> 'b t

same as apply

val (<*) : 'a t ‑> unit t ‑> 'a t
val (*>) : unit t ‑> 'a t ‑> 'a t

return x = Deferred.return (Ok x) *

include Core_kernel.Monad.S with type t := a t
type 'a t
include Base__.Monad_intf.S_without_syntax with type t := a t
type 'a t
include Base__.Monad_intf.Infix with type t := a t
type 'a t
val (>>=) : 'a t ‑> ('a ‑> 'b t) ‑> 'b 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 f v.

val (>>|) : 'a t ‑> ('a ‑> 'b) ‑> 'b t

t >>| f is t >>= (fun a -> return (f a)).

module Monad_infix : Base__.Monad_intf.Infix with type t := a t
val bind : 'a t ‑> f:('a ‑> 'b t) ‑> 'b t

bind t ~f = t >>= f

val return : 'a ‑> 'a t

return v returns the (trivial) computation that returns v.

val map : 'a t ‑> f:('a ‑> 'b) ‑> 'b t

map t ~f is t >>| f.

val join : 'a t t ‑> 'a t

join t is t >>= (fun t' -> t').

val ignore_m : 'a t ‑> unit t

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 Pervasives.ignore. Some monads still do let ignore = ignore_m for historical reasons.

val all : 'a t list ‑> 'a list t
val all_unit : unit t list ‑> unit t
val all_ignore : unit t list ‑> unit t
  • Deprecated [since 2018-02] Use [all_unit]
include Base__.Monad_intf.Syntax with type t := a t
type 'a t
module Let_syntax : sig ... end
val fail : Core_kernel.Error.t ‑> _ t

fail error = Deferred.return (Error error) *

val ignore : _ t ‑> unit t
val ok_exn : 'a t ‑> 'a Deferred.t

These functions are direct analogs of the corresponding Core.Or_error functions.

val of_exn : exn ‑> _ t
val of_exn_result : ('a, exn) Core_kernel.Result.t Deferred.t ‑> 'a t
val error : string ‑> 'a ‑> ('a ‑> Core_kernel.Sexp.t) ‑> _ t
val error_s : Core_kernel.Sexp.t ‑> _ t
val error_string : string ‑> _ t
val errorf : ('a, unit, string, _ tCore_kernel.format4 ‑> 'a
val tag : 'a t ‑> tag:string ‑> 'a t
val tag_arg : 'a t ‑> string ‑> 'b ‑> ('b ‑> Core_kernel.Sexp.t) ‑> 'a t
val unimplemented : string ‑> _ t
val combine_errors : 'a t list ‑> 'a list t
val combine_errors_unit : unit t list ‑> unit t
val find_map_ok : 'a list ‑> f:('a ‑> 'b t) ‑> 'b t

find_map_ok l ~f returns the first value in l for which f returns 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 ‑> ?⁠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.

The option 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 (extract_exn:false).

val try_with_join : ?⁠extract_exn:bool ‑> ?⁠here:Lexing.position ‑> ?⁠name:string ‑> (unit ‑> 'a t) ‑> 'a t
module List : Async_kernel.Monad_sequence.S with type monad := a t with type t := a list

All of the List functions that take a how argument treat it the following way: