package bap-future

  1. Overview
  2. Docs

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 Core_kernel.Std.Monad.S with type 'a t := 'a t
val (>>=) : 'a t -> ('a -> 'b t) -> 'b t
val (>>|) : 'a t -> ('a -> 'b) -> 'b t
module Monad_infix : sig ... end
val bind : 'a t -> ('a -> 'b t) -> 'b t
val join : 'a t t -> 'a t
val ignore_m : 'a t -> unit t
val all_ignore : unit t list -> unit t
module Let_syntax : sig ... end
include Core_kernel.Std.Applicative.S with type 'a t := '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 both : 'a t -> 'b t -> ('a * 'b) t
module Applicative_infix : sig ... end
val (<*>) : ('a -> 'b) t -> 'a t -> 'b t
val (<*) : 'a t -> unit t -> 'a t
val (*>) : unit t -> 'a t -> 'a t
module Variadic : Variadic.S with type 'a arg = 'a t
module Args : Core_kernel.Std.Applicative.Args with type 'a arg := 'a t
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

OCaml

Innovation. Community. Security.