Published: 20 Sep 2023
This OCaml module provides a API that is type- and dependency-abstracted across thread-local storage, Lwt's sequence-associated storage, and Eio's fiber-local storage — all different approaches to "throwing" information "across the stack" at runtime, without modifying interleaving methods/components/dependencies.
As a library author, depending on
ambient-context allows you to
abstract some sort of application-provided information into something like "thread-local storage",
while still being compatible with dependants who are calling into you from an asynchronous context (like Lwt or Eio),
without functorizing your interface over (or even depending on!) specifically Lwt or Eio, or preventing non-Lwt/Eio users from consuming your API.
ambient-context allows you to communicate with your dependants in situations where you cannot control intermediate dependencies, and cannot modify the API of your own library to accept a new parameter.
Installation and usage ...
The intended usage of this library is in two collaborating components:
that of a "deep in the dependency-tree" library (e.g.
and a top-of-the-dependency-tree (e.g.
The former needs to be able to obtain information from the latter, without changing the API presented to intermediate dependencies (e.g.
bar-intermediary-lib) — and equivalently, without changing the function-signatures of intermediate wrappers/callers.
... as a top-level application
If a library you depend on (let's pretend it's
ambient-context, they're effectively deferring an important decision about how their library communicates with you.
This means you must to choose, and configure, a storage-mechanism relevant to the callsite(s) in your own application.
Your choice will vary depending on from where, in your own code, you're calling into a library that uses
ambient-context — that is, whether an asynchronous event-loop (such as Lwt or Eio) exists 'above' your calls on the stack. Having determined whether you'll be calling your dependancy (e.g.
foo-deep-lib) from such an asynchronous context , you'll then need to install the relevant storage-provider at runtime with an appropriately-placed call to
Once your application has configured the appropriate runtime context-storage, you'll presumably need to actually use the ambient context in your calls to
To communicate with transitive dependencies, you need an opaque
key — these are usually created and exposed by your transitive dependency; see its documentation.
You can provide ambient values to the transitive dependency via calls to
Ambient_context.with_binding; which takes that opaque
key, the new
value you want to set, and then a callback.
Refer to your dependency's documentation for specific instructions on how to provide the ambient context they expect.
... as a library
This library allows you to avoid depending on, or functorizing over,
Lwt.t. In the most basic usage, you simply provide a
Ambient_context.key, direct your consumers to the above documentation and then anywhere in your API, you can pull the value 'currently' assigned to your key out of the ambient-context.
You need depend only on
ambient-context itself, not
ambient-context-lwt, or even
; dune-project (depends (ocaml (>= 4.08)) + ambient-context (alcotest :with-test) (ocaml-lsp-server :with-dev-setup)
; lib/dune (library (name foo-deep-lib) - (libraries curl pcre) + (libraries ambient-context curl pcre))
Ambient_context.create_key to create an opaque key for the value, and expose that to your user:
(* lib/foo_deep.ml *) module Ctx = Ambient_context let header_context_key : string Ctx.key = Ctx.create_key () (* ... *)
Then, anywhere you like, you should be able to obtain the value assigned to
Foo_deep.header_context_key by the consuming application up-stack from you:
(* lib/foo_deep.ml *) module Ctx = Ambient_context (* ... *) let http_request ?headers ?body action url = let open Curl in let headers = match Ctx.get Foo_deep.header_context_key with | None -> headers | Some header -> let header = "x-foo-deep: " ^ header in Some (header :: Option.default  headers) in (* ... *)
Create an opam switch and install the dependencies:
$ opam switch create . ocaml.5.0.0 --deps-only --no-install # If you have opam >= 2.2 $ opam install . --deps-only --with-test --with-dev-setup # ... or with opam < 2.2 $ opam install . --deps-only --with-test $ opam install ocaml-lsp-server ocamlformat
Install pre-commit, and then configure your checkout:
$ pre-commit install pre-commit installed at .git/hooks/pre-commit
Copyright © 2023 ELLIOTTCABLE
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.