Module Fut.Runtime

Runtime system configuration and interaction.

val name : string

name is the backend name.

Exception trap

See also the section about exceptions.

type exn_ctx = [
| `Queue of string
| `Future
| `Finalizer
| `Backend
| `Fd_action
| `Timer_action
| `Signal_action
| `Runtime_action
| `Exn_trap
]

The type for exception contexts.

type exn_info = exn_ctx * exn * Stdlib.Printexc.raw_backtrace

The type for info about trapped exceptions. The context, the exception, and the backtrace.

val set_exn_trap : (exn_info -> unit) -> unit

set_exn_trap h is a function called whenever the runtime system traps an exception.

val pp_exn_info : Stdlib.Format.formatter -> exn_info -> unit

pp_exn_info ppf i prints an unspecified representation of i on ppf.

Actions

type abort = unit -> unit

The type for action's abort functions. Calling an abort function associated to an action function has the following effects and must be guaranteed by the backends:

  • If the action wasn't executed yet. It guarantees that action will never be called and will be eventually gc'd.
  • If the action was already executed, it has no effects.

Runtime actions

val action : (unit -> unit) -> unit

action a executes a () as soon as possible on the runtime system thread. Actions are executed in FIFO order as received.

Thread-safe. This function can be called from other threads.

Signal actions

val signal_action : int -> (abort -> (int -> unit) * 'a) -> 'a

signal_action s def calls def with an abort function to get (action,v). The function action is scheduled for execution whenever the next signal s is received and will be called once with s when that happens or never if abort was called before, see abort for details. The value v is simply returned by signal_action.

Timer actions

val timer_action : float -> (abort -> (float -> unit) * 'a) -> 'a

timer_action d def calls def with an abort function to get (action,v). The function action is scheduled for execution in d seconds and will be called once with the actualy delay that was performed or never if abort was called before, see abort for details. The value v is simply returned by timer_action.

File descriptor actions and closing

val fd_action : [ `R | `W ] -> Unix.file_descr -> (bool -> unit) -> unit

fd_action fds fd a executes a true whenever fd is in the state fds. If fd is closed a false executed.

val fd_close : Unix.file_descr -> unit

TODO

Workers

Note. Most of the time a worker maps to a system thread, but the exact semantics is backend dependent. Workers are typically used to determine the future of futures queues.

Threads. If a backend uses threads it guarantees that the number of threads is 0 before any call is made to Fut.apply or set_worker_count. This allows to fork TODO we need more to be able to fork.

val worker_count : unit -> int

worker_count () is the number of workers used by the backend.

val set_worker_count : int -> unit

set_worker_count n sets the number of workers to n.

raises Invalid_argument

if n is negative.

Note. Clients don't need to call this function explicitely, backends will automatically adjust workers once Fut.apply is called. Also if the number of workers is set to 0, a new call to Fut.apply may change the worker count again.

Warning. In most backends calling this function explicitely with n > 0 makes the program multithreaded..