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 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.Applicative.S with type 'a t := 'a t
val both : 'a t -> 'b t -> ('a * 'b) t
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
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
module Applicative_infix : sig ... end

return x = Deferred.return (Ok x) *

include Core.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 Stdlib.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

Like 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 Core.Or_error functions.

val of_exn : ?backtrace:[ `Get | `This of string ] -> exn -> _ t
val of_exn_result : ?backtrace:[ `Get | `This of string ] -> ('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 : 'a t -> tag:string -> 'a t
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
val combine_errors : 'a t list -> 'a list t
val combine_errors_unit : unit t list -> unit t
val filter_ok_at_least_one : 'a t list -> 'a list 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 -> ?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.

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).

The ~rest argument controls how exceptions are handled after the try_with deferred becomes determined. They may be logged, raised, or passed to a callback.

The ~run argument controls when f gets called. `Now calls f immediately; `Schedule schedules an asynchronous job to run f.

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.

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