package async_kernel

  1. Overview
  2. Docs
package async_kernel
Legend:
Library
Module
Module type
Parameter
Class
Class type

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 : sig ... end

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 'a t := 'a t
val apply : ('a -> 'b) t -> 'a t -> '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 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 'a t := '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 : sig ... end
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]
module Let_syntax : sig ... end

These are convenient to have in scope when programming with a monad:

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, _ t) Core_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 : 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:

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct