package shuttle

  1. Overview
  2. Docs
Reasonably performant non-blocking channels for async

Install

Dune Dependency

Authors

Maintainers

Sources

shuttle-0.9.2.tbz
sha256=69bf4d3ec9262dc981db5b6073c1d9e581c24fa1f1a49d20798eb3ae953ecdc3
sha512=36e95dcfce349f1acc586afa30c6b74d8212b9a8c0e32a2abcdbe09a87208b9ed2dc2c27aed3d65f4e9031260a3c54af7d0e9ebd7ba3d0b80182f17773dae24f

Description

Tags

async reader writer

Published: 20 Feb 2023

README

Shuttle

Reasonably performant buffered channels1 for async.

Overview

There are multiple options for performing I/O using async. The Reader and Writer modules provide a high level API for buffered I/O, and are typically the go-to option for applications that use async for I/O. These modules maintain their own internal buffer, and offer users a simple interface that lets them interact with the underlying file descriptor without having to write custom (and often error prone) buffer management logic.

The Reader/Writer modules provide convinence, but they might not be suitable in scenarios where one wants slightly more control over when write operations are scheduled, or when the overhead of the reader/writer is not desirable2. In such scenarios, it is possible to drop down to async's Fd module and schedule reads and writes manually. This approach will give full control over how I/O operations are scheduled, but will come at a cost of more complexity as the user is now responsible for buffer management, and proper handling of syscall responses.

Shuttle aims to provide a middle ground for a subset of use-cases handled by Reader/Writer. It covers fewer use-cases when compared to Reader/Writer, only supports file descriptors that support non-blocking system calls, and doesn't aim to support the full feature set of the reader/writes modules. In return, it allows for a high level api that pairs the ease of use of reader/writer modules with performance and latency curves that are closer to implementations with manual buffer management.

Supported Platforms

Currently only linux, macOS and bsd based systems.

How to Install

opam install shuttle for the current published release, and opam pin add shuttle --dev-repo for the development version.

Companion projects

  • shuttle_ssl: Async_ssl support for shuttle

  • shuttle_http: Http 1.1 server and client support built on top of shuttle.

Notes:

  • 1: Channel is a high-level construct for performing I/O.

  • 2: As always, make your own measurements. Also weigh in the fact that reader/writer modules in async are mature, battle tested and cover more use-cases.

  • 3: The implementation started as a fork async_rpc's low latency transport.

  • 4: A shuttle based http server benchmark can be found at https://github.com/ocaml-multicore/retro-httpaf-bench/pull/16

Dependencies (6)

  1. ppx_jane >= "v0.15.0"
  2. core_unix >= "v0.15.0"
  3. core >= "v0.15.0"
  4. async >= "v0.15.0"
  5. ocaml >= "4.11.0"
  6. dune >= "2.8"

Dev Dependencies (1)

  1. odoc with-doc

Used by (2)

  1. shuttle_http = "0.9.2"
  2. shuttle_ssl = "0.9.2"

Conflicts

None