package ambient-context

  1. Overview
  2. Docs

Ambient context.

The ambient context, like the Matrix, is everywhere around you.

It is responsible for keeping track of that context in a manner that's consistent with the program's choice of control flow paradigm:

  • for synchronous/threaded/direct style code, TLS ("thread local storage") keeps track of a global variable per thread. Each thread has its own copy of the variable and updates it independently of other threads.
  • for Lwt, any 'a Lwt.t created inside the with_binding k v (fun _ -> …) will inherit the k := v assignment.
  • for Eio, fibers created inside with_binding k v (fun () -> …) will inherit the k := v assignment. This is consistent with the structured concurrency approach of Eio.

The only data stored by this storage is a Hmap.t, ie a heterogeneous map. Various users (libraries, user code, etc.) can create their own key to store what they are interested in, without affecting other parts of the storage.

module type STORAGE = Types.STORAGE
type storage = (module STORAGE)
val default_storage : Types.storage
val get_current_storage : unit -> Types.storage
val set_storage_provider : Types.storage -> unit
type 'a key

A key that can be mapped to values of type 'a in the ambient context.

val compare_key : int -> int -> int

Total order on keys

val create_key : unit -> 'a key

Create a new fresh key, distinct from any previously created key.

val get : 'a key -> 'a option

Get the current value for a given key, or None if no value was associated with the key in the ambient context.

val with_binding : 'a key -> 'a -> (unit -> 'r) -> 'r

with_binding k v cb calls cb() in a context in which k is bound to v. This does not affect storage outside of cb().

val without_binding : 'a key -> (unit -> 'b) -> 'b

without_binding k cb calls cb() in a context where k has no binding (possibly shadowing the current ambient binding of k if it exists).

OCaml

Innovation. Community. Security.