Module Fut

Applicative combinators

These combinators have no effects on the determination of their arguments.

Effectful combinators

These combinators may set their `Undetermined arguments to `Never and abort their determination.

Important. When a future is aborted, it is set to never determine and all the future it may be waiting on (and recursively) are also aborted, except those that are protected by protect. Aborting a future that is set has no effect since once the future is set it never changes again.

Warning. If the aborted future is an `Undetermined future from a future queue, there's no guarantee that the corresponding application will be/has not been executed when it is set to `Never. In any case the semantics of futures is preserved, it will switch from `Undet to `Never and remain so forever but depending on what the function application does, the world may be affected.

Semantics

The semantic function []: 'a Fut.t -> time -> 'a Fut.state gives meaning to a future f by mapping it to a function [f] that give its state at any point in time (after its creation). We write [f]_t the evaluation of this semantic function at time t.

Remember that once a future is set it never changes again. This is captured by the following axiom that holds for any future f at any time t:

• If [f]_t <> `Undet then for all t' > t we have [f]_t' = [f]_t

The semantics of combinators are given in terms of [] by describing only the instants at which the resulting future is set. In the remaining undescribed instants the state of the future is implicitly taken to be unset, i.e. `Undetetermined. The descriptions also implicitly quantify universally over the free variable t.

Never determined futures

Fut makes a distinction between a future that is undetermined and may remain so forever and a future that is known to be never determined (e.g. Fut.never), a future with state `Never. Futures depending on a future value that `Never determines also never determine. This means that most combinator whenever they are given a future that never determines return a future that never determines.

One way to get never determined futures is by using the future exclusive choice combinator first between two futures. The first one that determines makes the other become never determined. Note that for future created with Fut.apply, the application (and its effects) may (or not) still be executed, but it's value is discarded.

Exceptions

If the computation to determine a future's value raises an exception it is set to `Never determine and the exception is logged by the runtime system to the handler provided by Runtime.set_exn_trap. The default handler is backend dependent but usually logs the exception on stderr.

There is a single exception to this behaviour. If the exception Never is raised by an application given to Fut.apply, the corresponding future never determines but the exception is not logged.

Do not rely on the fact that exceptions are automatically trapped by the system, this mechanism is in place so that unexpected exceptions do not kill the runtime system for long running programs. If you deal with a library that is designed around exceptions you should catch and handle them, if only to use Fut.never if you wish so. For example if looking up a data structure may return Not_found don't do that:

let find k m = Fut.ret (M.find k m)

This may significantly obfuscate what's happening (and won't be efficient). Explicitely handle the exception:

let find k m = try Fut.ret (M.find k m) with Not_found -> Fut.never ()

In this example, using option types may anway be clearer:

let find k m = Fut.ret (try Some (M.find k m) with Not_found -> None)

Future queues

Future queues determine long-running or blocking function applications with a set of concurrent workers usually implemented as system threads.

A future queue determines the applications submitted to it through the Fut.apply function sequentially and in FIFO order. This property also makes them a mutual exclusion synchronization primitive. Applications submitted in two different queues are determined concurrently. In the following examples f1 and f2 will be set sequentially, while f3 will do so concurrently to those.

let q1 = Fut.Queue.create ()
let q2 = Fut.Queue.create ()
let f1 = Fut.apply ~queue:q1 Printf.printf "first f1"
let f2 = Fut.apply ~queue:q1 Printf.printf "then f2"
let f3 = Fut.apply ~queue:q2 Printf.printf "f3 at anytime"

Note that the function applications are executed on another threads and as such must respect Fut's thread safety rule.

There is a special queue the concurrent queue which is the default argument of apply. This queue has no FIFO ordering constraint: anything submitted to it is determined concurrently. It is useful to just apply a long-running function to avoid starving the runtime system:

let long_work = Fut.apply long_running_function ()

It is also possible to provide a reference cell abort to apply. This reference cell will be set true by the runtime system if the future is aborted by the runtime system. This can be used to stop the application. For example:

let long_running_work abort =
  while (not !abort || !finished) do ... done

let abort = ref false
let long_work = Fut.apply ~abort long_running_work abort
let _ = Fut.abort long_work (* will set abort to [true] *)

Note that the runtime system never reads abort it just sets it to true when appropriate.

Promises

Promises are used to expose the functionality of third-party libraries as futures. A call to promise returns a promise that has an associated future (returned by future). The promise can be set, which sets the associated future. See this example to see how promises can be used to expose callback based asynchronous interfaces as futures.

Note that Fut.set must be called on Fut's thread. If one needs to set futures from another thread, a Runtime.action can be used. See the next section.

Fut and system threads

Except for applications determined on future queues, Fut has a single-threaded cooperative concurency model. This means that at any time there's only one future that is trying to determine its value on Fut's thread.

Thread-safety rule. The thread-safety rule of Fut is simple. A single thread must run Fut's runtime system via a call to await and no other thread is allowed to use any function of Fut except, promise, future, state and Runtime.action.

In particular the thread-safety rule does apply to function applications performed with Fut.app as they are performed on other threads.

Fut tries to abstract away all your thread needs via the concept of future queues. Sometimes this is however infeasible for example because a library prevents you from sharing structures across threads and future queues provides you no support to control on which thread an application will happen. In that case you can still create your own system thread and interact with Fut by using promise and a Runtime.action to Fut.set it once it determined. See this example.

Before any call to apply or Runtime.set_thread_count the program is single threaded.

Fut and system processes

In general Unix.fork does not cope well with threads. The best approach is thus to fork all the processes you need before the first call to await.

Backends

TODO explain how to link against a backend.

The universal client

The echo server

Integration with asynchronous functions

Suppose we have a function to perform asynchronous reads on a regular file whose signature is as follows:

type read = [ `Error | `Read of int ]
val Aio.read : Unix.file_descr -> string -> int -> int -> (read -> unit) -> unit

where read fd s j l k tries to read l bytes from fd to store them in s starting at j calling k when it has completed.

Exposing this function call as a future is very simple. Create a promise and set it in the callback k:

val read : Unix.file_descr -> string -> int -> int -> read Fut.t
let read fd s j l =
  let p = Fut.promise () in
  let k r = Fut.set p (`Det r) in
  Aio.read fd s j l k;
  Fut.future p

It is however important to make sure that the thread that calls the continuation k is Fut's thread. If this is not the case the callback k can be replaced by:

let k r = Fut.Runtime.action (fun () -> Fut.set p (`Det r))

Integration with threads

If for some reason you cannot use future queues and need to run a service in its own thread, the code below shows how to interact with Fut and respect its thread-safety rule.

module Service : sig
  type request
  type response
  val request : request -> response Fut.t
  val run : unit -> unit
end = struct
  type request
  type response

  let m = Mutex.create ()
  let not_empty = Condition.create ()
  let requests = Queue.create ()

  let request req = (* executed by [Fut]'s thread. *)
    let abort' = ref false in
    let abort () = abort' := true in
    let promise = Fut.promise ~abort () in
    Mutex.lock m;
    Queue.add (req, promise, abort') requests;
    Condition.signal not_empty;
    Mutex.unlock m;
    Fut.future promise

  let rec serve () = (* executed by the service's thread. *)
    Mutex.lock m;
    while Queue.is_empty requests do Condition.wait not_empty m done;
    let (req, promise, abort) = Queue.pop requests in
    Mutex.unlock m;
    let resp = do_service req abort in
    let set () = Fut.set promise (`Det resp) in
    if not !abort then Fut.Runtime.action set;
    serve ()

    let run () = ignore (Thread.create serve ())
end

Integration with multiprocessing

You may want to use futures to delegate work to other processes.

Integration with signals