Awesome Multicore OCaml

A collection of libraries, experiments and ideas relating to OCaml 5 (multicore + effects). With the merging of the main multicore-ocaml branch into OCaml trunk, a parallel and effectful world is fast approaching.

This repository collects useful libraries, ideas and experiments relating to the use of Multicore OCaml features (primarily parallelism with domains and direct-style code with effects).

For contributing, see the guide.

If you are wondering what even is Multicore OCaml, you could start by watching KC's keynote at ICFP 2022. To know more about how Multicore OCaml evolved over the years, see this video from 2014 about Multicore OCaml by Stephen Dolan and co., then one on how to parallelise your OCaml code and how we can adapt the existing ecosystem to support Multicore OCaml.

For understanding effects in OCaml 5 you can watch KC Sivaramakrishnan's Effective Programming in OCaml 5 talk and also Thomas Leonard's talk at the 2021 OCaml Workshop on Experiences with Effects. Note both videos use a syntax for effects that will not exist in OCaml 5.00 (see also ppx_effects).

For more resources like this, check the Multicore OCaml wiki.

There's a WIP PR to start submoduling repositories so it can be a one-stop shop for taking OCaml 5.00 for a spin, see the PR.

Table of Contents

• Installation
• Libraries
  • Eio
  • Affect
  • Domainslib
  • Lockfree
  • Lwt Support
  • Async Support
  • Parany
  • Processor
  • cohttp-eio
  • mirage-crypto-rng-eio
  • Js_of_ocaml support
  • ocaml-tls
• Testing
  • multicoretests
• Tooling
  • Olly
  • Eio-console
  • TSan
• Experiments
  • Dream
  • Ppx_effects
  • Gemini Protocol
  • Multi-shot Continuations
  • Mirage network
  • Capnp-rpc
  • gRPC
• Ideas
  • Non-blocking Codec
• Resources
  • Wiki
  • Discuss Threads
  • Monthlies
  • Benchmarks

Installation

OCaml 5 is out! The compiler can be obtained with the following instructions on Linux and Mac machines.

λ opam update
λ opam switch create 5.0.0
λ eval $(opam env)

Libraries

Eio

Repository: https://github.com/ocaml-multicore/eio

Eio implements an effects-based direct-style IO stack for multicore OCaml. It supports multiple backends including a performant io-uring one and a portable libuv backend. A 0.1 release is now available from opam-repository.

Affect

Repository: https://erratique.ch/software/affect

Affect provides composable concurrency primitives for OCaml using the effect handlers available in OCaml 5.0. Affect should be seen as an experiment at that point.

Domainslib

Repository: https://github.com/ocaml-multicore/domainslib

Domainslib provides data-structures for parallel programming on top of multicore primitives. This includes a work-stealing task pool and channels for inter-domain communication.

Lockfree

Repository: https://github.com/ocaml-multicore/lockfree

Lock-free is collection of non-blocking data structures for multicore OCaml.

Lwt Support

Some useful and relevant OCaml.5 x Lwt discussions:

• Is mixing lwt and multicore safe?
• Multicore, Async and Lwt

Lwt_eio

Repository: https://github.com/talex5/lwt_eio

Lwt_eio provides an "lwt engine" using Eio making it possible to use both Eio and Lwt in the same codebase. A 0.1 release is now available from opam-repository.

Lwt_domain

Repository: https://github.com/ocsigen/lwt

Lwt now has a package called lwt-domain. This provides useful functions for programming with Lwt and Domainslib.

Async Support

Async_eio

Repository: https://github.com/talex5/async_eio

Async_eio allows running Async and Eio code together in a single domain. It allows converting existing code to Eio incrementally.

Parany

Repository: https://github.com/UnixJunkie/parany/tree/domains

The Parany git branch called "domains" is compatible with multicore-ocaml.

OCaml Processor

Repository: https://github.com/haesbaert/ocaml-processor

The library allows you to query the processor topology as well as set the processor affinity for the current process.

cohttp-eio

Repository: https://github.com/mirage/ocaml-cohttp/tree/master/cohttp-eio

cohttp-eio is a HTTP client and server library built using eio. It enables monad-less, direct style programming of multi-core capable HTTP web server and client applications. Monads be gone.

mirage-crypto-rng-eio

Repository: https://github.com/mirage/mirage-crypto/tree/main/rng/eio

mirage-crypto-rng-eio allows to use various crypto functions in an eio application.

Js_of_ocaml

Repository: https://github.com/ocsigen/js_of_ocaml

js_of_ocaml supports effects through CPS transformations - this means one can start running effects in browsers! Implementation details can be found in Jérôme Vouillon 's PR

ocaml-tls

Repository: https://github.com/mirleft/ocaml-tls

tls_eio supports effectful operations using Eio.

Testing

Multicoretests

Repository: https://github.com/jmid/multicoretests

Experimental property-based tests of (parts of) the OCaml multicore compiler. The project contains a randomized testsuite of OCaml 5.0 based on QCheck and two reusable testing libraries Lin and STM.

Tooling

Olly

Repository: https://github.com/sadiqj/runtime_events_tools

A collection of observability tools around the runtime events tracing system introduced in OCaml 5.0.

Eio-console

Repository: https://github.com/patricoferris/eio-console

Eio-console provides an application for monitoring running programs. This works in the browser, communicating information over a websocket.

TSan

Repository: https://github.com/OlivierNicole/ocaml-tsan

ThreadSanitizer (TSan) is an effective approach to locate data races in parallel code. This extended version of the OCaml compiler generates instrumented executables that will print error reports if a data race is detected.

Experiments

Dream

Repository: https://github.com/talex5/dream/tree/eio

See also the draft PR that uses Dream, Eio and lwt_eio to provide a direct-style interface to Dream.

Ppx_effects

Repository: https://github.com/CraigFe/ppx_effects

The effects in OCaml 5 will not support a dedicated syntax, but plans exist for this perhaps once the effects are typed. Until then this ppx provides an approximation to the proposed syntax.

Gemini Protocol

Repository: https://gitlab.com/talex5/gemini-eio

The gemini protocol implemented in direct-style using eio.

Multi-shot Continuations

Repository: https://github.com/dhil/ocaml-multicont

Built on top of the continuations in Multicore OCaml, ocaml-multicont provides a library for using continuations that can be applied more than once. See also this discussion on discuss.

Mirage networking experiments

Repository: https://github.com/TheLortex/networking-experiments

Goal is to port Mirage's TCP/IP stack on top of OCaml 5's effects for more manageable async code.

capnp-rpc

Cap'n Proto is a capability-based RPC system with bindings for many languages. The Eio port switches capnp-rpc from Lwt to Eio.

gRPC

gRPC is a high performance, open source, general RPC framework that puts mobile and HTTP/2 first. The Eio port adds native Eio support for OCaml gRPC.

Ideas

Even less further on than experiments, the ideas section contains projects that would benefit from the features of Multicore OCaml.

Non-blocking Codec

Repository: https://github.com/dbuenzli/nbcodec

Many libraries and tools written in the nbcodec style would benefit from continuations given by effect handlers in Multicore OCaml, including libraries like jsonm or xmlm perhaps.

Resources

Wiki

The Multicore OCaml Wiki contains a lot of useful information from design decisions to examples. Two notable repositories are:

• Effects examples: a collection of great examples with effects including cooperative threading and generators.
• Parallel Programming in Multicore OCaml: a very good introduction to programming parallel programs in Multicore OCaml, including using Domainslib.

Papers

• Retrofitting Effect Handlers onto OCaml, PLDI, June 2021: Describes the design and evaluation of a full-fledged efficient implementation of effect handlers for OCaml.
• Parallelising your OCaml code with Multicore OCaml, OCaml Workshop, August 2020: A tour on developing parallel programs with Multicore OCaml.
• Retrofitting Parallelism onto OCaml, ICFP, August 2020: Deep dive into Multicore GC design.
• Multicore OCaml memory model, PLDI, June 2018: Describes the memory model for multicore OCaml programs. This memory model is much simpler than existing language memory models such as Java or C/C++11 without sacrificing performance.
• Concurrent System Programming with Effect Handlers, TFP, February 2018: Using effect handler for writing concurrent programs that interacts with the operating system.
• Multicore OCaml, OCaml workshop, September 2014.

Talks

• Introduction to Eio, Thomas Leonard, February 2023. (video)
• k-CAS for sweat-free concurrent programming, Vesa Karvonen, February 2023. (video)
• Retrofitting Concurrency – Lessons from the Engine Room, KC Sivaramakrishnana, September 2022. (video)
• Experiences with Effects in OCaml, Thomas Leonard, August 2021. (video)
• Parafuzz: Coverage-guided Property Fuzzing for Multicore OCaml programs, KC Sivaramakrishnan, August 2021. (video)
• Adapting the OCaml Ecosystem for Multicore OCaml, Sudha Parimala, August 2021. (video)
• Effective Programming in OCaml, KC Sivaramakrishnan, April 2021. (video)
• Multicore OCaml -- what's coming in 2021, KC Sivaramakrishnan, December 2020. (video)
• Parallelising your OCaml code with Multicore OCaml, Sadiq Jaffar August 2020. (video)
• Retrofitting parallelism onto OCaml, KC Sivaramakrishnan, August 2020. (video)
• A deep dive into Multicore OCaml GC, KC Sivaramakrishnan, June 2017.
• Reagents: Lock-free programming for the masses, KC Sivaramakrishnan, August 2016. (video).
• Arrows and Reagents, KC Sivaramakrishnan, March 2016.
• Concurrent & Multicore OCaml: A deep dive, KC Sivaramakrishnan, January 2016.
• Effective Concurrency with Algebraic Effects, KC Sivaramakrishnan, OCaml Workshop, September 2015.
• Multicore OCaml, Stephen Dolan, OCaml workshop, September 2014. (video).

Discuss Threads

Recently, there has been a lot of great discussion on discuss.ocaml.org around OCaml 5, in particular what the ramifications of adding effects to the language will have to the ecosystem:

• The initial release of Eio has a lot of dicussion around what it could mean if the library became the official "OCaml IO" library. It also has some useful conversations about the underlying use of effects in Eio and in particular the set of private effects used.
  • An excellent write up about scopes and effect handlers was added in this thread.
• Another thread, "How to block in an agnostic way", is a discussion about blocking code where we are agnostic to the underlying concurrency abstraction (and indeed how to do interop between libraries).
• Another more Eio-specific thread looks at cancellation in the presence of concurrency from effects.
• In How do spawn and join interact with try_with there's a great, short discussion about effects in the presence of multiple domains. A "gotcha" many (myself included) are likely to hit when getting started with OCaml 5.
• There is a great discussion about using effects for a roguelike game in Tutorial: Roguelike with Effect Handlers (the full tutorial is here). Related to that is another excellent article about coding animations with effect handlers.

Monthlies

The OCaml monthlies are available on discuss: https://discuss.ocaml.org/tag/multicore-monthly

Benchmarks

Sandmark

Repository: https://github.com/ocaml-bench/sandmark

Sandmark is a suite of OCaml benchmarks and a collection of tools to configure different compiler variants, run and visualise the results.

Sandmark nightly runs the Sandmark benchmarks and visualises results: https://sandmark.tarides.com/?app=Home

Http Benchmarks

Repository: https://github.com/ocaml-multicore/retro-httpaf-bench

A collection of HTTP servers including ones in Go, Rust, multiple OCaml implementations and OCaml with effects.