Home

Awesome

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

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:

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.

algaeff

Repository: https://github.com/RedPRL/algaeff

algaeff is a collection of well-known reusable effects-based components (states, generators, etc.) packaged as an OPAM library.

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:

Papers

Talks

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:

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.