Module Std.Future

Future is an object whose value will be decided somewhere in the future, if that future has occurred.

Futures can be seen as memory cells that can be set only once, thus having two states: empty and filled.

A future may occur at some point of physical time. A future is total. If a promise cannot be fulfilled due to an error, that just means, that in this world this future is not possible. Thus the future object models nonlinear tree-like time. To represent a computation, that has different futures, one can use either a sum type as a future value, or a tuple of futures. The former is preferred, if different future is decidable (i.e., only one path is possible). The latter is preferred if different variants are possible.

A future is a monad, and it is preferred to work with the future via the monadic interface, e.g.,

let first_insn mem pc : mem Or_error.t future =
  Future.(Stream.nth pc 0 >>= fun fst ->
          Stream.nth pc 1 >>= fun snd ->
          return (Memory.range mem fst snd))

Note: the future is a common denominator between lwt thread, async deferred, native ocaml event, or any other value, that is defined asynchronously. Once can also think of futures and threads as a software pattern to work with callbacks.

type 'a t = 'a future
include Monads.Std.Monad.S with type 'a t := 'a t
val void : 'a t -> unit t

void m computes m and discrards the result.

val sequence : unit t list -> unit t

sequence xs computes a sequence of computations xs in the left to right order.

val forever : 'a t -> 'b t

forever xs creates a computationt that never returns.

module Fn : sig ... end

Various function combinators lifted into the Kleisli category.

module Pair : sig ... end

The pair interface lifted into the monad.

module Triple : sig ... end

The triple interface lifted into a monad.

module Lift : sig ... end

Lifts functions into the monad.

module Exn : sig ... end

Interacting between monads and language exceptions

module Collection : sig ... end

Lifts collection interface into the monad.

module List : Collection.S with type 'a t := 'a list

The Monad.Collection.S interface for lists

module Seq : Collection.S with type 'a t := 'a Core_kernel.Sequence.t

The Monad.Collection.S interface for sequences

include Monads.Std.Monad.Syntax.S with type 'a t := 'a t
val (>=>) : ('a -> 'b t) -> ('b -> 'c t) -> 'a -> 'c t

f >=> g is fun x -> f x >>= g

val (!!) : 'a -> 'a t

!!x is return x

val (!$) : ('a -> 'b) -> 'a t -> 'b t

!$f is Lift.unary f

val (!$$) : ('a -> 'b -> 'c) -> 'a t -> 'b t -> 'c t

!$$f is Lift.binary f

val (!$$$) : ('a -> 'b -> 'c -> 'd) -> 'a t -> 'b t -> 'c t -> 'd t

!$$$f is Lift.ternary f

val (!$$$$) : ('a -> 'b -> 'c -> 'd -> 'e) -> 'a t -> 'b t -> 'c t -> 'd t -> 'e t

!$$$$f is Lift.quaternary f

val (!$$$$$) : ('a -> 'b -> 'c -> 'd -> 'e -> 'f) -> 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t

!$$$$$f is Lift.quinary f

include Monads.Std.Monad.Syntax.Let.S with type 'a t := 'a t
val let* : 'a t -> ('a -> 'b t) -> 'b t

let* r = f x in b is f x >>= fun r -> b

val and* : 'a t -> 'b t -> ('a * 'b) t

monoidal product

val let+ : 'a t -> ('a -> 'b) -> 'b t

let+ r = f x in b is f x >>| fun r -> b

val and+ : 'a t -> 'b t -> ('a * 'b) t

monoidal product

include Core_kernel.Monad.S with type 'a t := 'a t
val (>>=) : 'a t -> ('a -> 'b t) -> 'b t
module Monad_infix : sig ... end
val bind : 'a t -> f:('a -> 'b t) -> 'b t
val join : 'a t t -> 'a t
val ignore_m : 'a t -> unit t
module Let_syntax : sig ... end
module Let : Monads.Std.Monad.Syntax.Let.S with type 'a t := 'a t

Monadic operators, see Monad.Syntax.S for more.

module Syntax : Monads.Std.Monad.Syntax.S with type 'a t := 'a t

Monadic operators, see Monad.Syntax.S for more.

include Core_kernel.Applicative.S with type 'a t := 'a t
val return : 'a -> 'a t
val map : 'a t -> f:('a -> 'b) -> 'b t
val both : 'a t -> 'b t -> ('a * 'b) t
val (<*>) : ('a -> 'b) t -> 'a t -> 'b t
val (<*) : 'a t -> unit t -> 'a t
val (*>) : unit t -> 'a t -> 'a t
val (>>|) : 'a t -> ('a -> 'b) -> 'b 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 all : 'a t list -> 'a list t
val all_unit : unit t list -> unit t
module Applicative_infix : sig ... end
module Variadic : Variadic.S with type 'a arg = 'a t
module Args : sig ... end
val create : unit -> 'a t * 'a promise

create () creates a new future. The function returns a pair of the future itself and a promise that can be used to fulfill the future.

val upon : 'a t -> ('a -> unit) -> unit

upon f action will call action as soon a future f occurs.

val is_decided : 'a t -> bool

is_decided f is true if a future f is already decided.

val peek : 'a t -> 'a option

peek f will return Some value if future f has already occurred with this value.

val peek_exn : 'a t -> 'a

peek_exn f will evaluate to x iff is_decided f && peek f x = Some x