nanoev/picos/_doc-dir/odoc-pages/index.mld

{0 Picos — Interoperable effects based concurrency}

This packages contains the core {!Picos} interface library and auxiliary
libraries for dealing with the OCaml multithreading architecture.

{1 Libraries}

{!modules:
  Picos
  Picos_domain
  Picos_thread
}

{1 Introduction}

{!Picos} is a {{:https://en.wikipedia.org/wiki/Systems_programming} systems
programming} interface between effects based schedulers and concurrent
abstractions.  Picos is designed to enable an ecosystem of
{{:https://en.wikipedia.org/wiki/Interoperability} interoperable} elements of
{{:https://v2.ocaml.org/manual/effects.html} effects based}
{{:https://en.wikipedia.org/wiki/Cooperative_multitasking} cooperative}
{{:https://en.wikipedia.org/wiki/Concurrent_computing} concurrent programming
models} such as

- {{:https://en.wikipedia.org/wiki/Scheduling_(computing)} schedulers} that
  multiplex large numbers of {{:https://en.wikipedia.org/wiki/Green_thread} user
  level fibers} to run on a small number of system level threads,
- mechanisms for managing fibers and for
  {{:https://en.wikipedia.org/wiki/Structured_concurrency} structuring
  concurrency},
- communication and synchronization primitives, such as
  {{:https://en.wikipedia.org/wiki/Monitor_(synchronization)} mutexes and
  condition variables}, message queues,
  {{:https://en.wikipedia.org/wiki/Software_transactional_memory} STMs}, and
  more, and
- integrations with low level {{:https://en.wikipedia.org/wiki/Asynchronous_I/O}
  asynchronous IO} systems.

If you are the author of an application level concurrent programming library or
framework, then Picos should not fundamentally be competing with your work.
However, Picos and libraries built on top of Picos probably do have overlap with
your work and making your work Picos compatible may offer benefits:

- You may find it useful that the {{!Picos} core} of Picos provides parallelism
  safe building blocks for cancelation, which is a particularly tricky problem
  to get right.
- You may find it useful that you don't have to reinvent many of the basic
  communication and synchronization abstractions such as mutexes and condition
  variables, promises, concurrent bounded queues, channels, and what not.
- You may benefit from further non-trivial libraries, such as IO libraries, that
  you don't have to reimplement.
- Potential users of your work may be reassured and benefit from the ability to
  mix-and-match your work with other Picos compatible libraries and frameworks.

Of course, interoperability does have some costs.  It takes time to understand
Picos and it takes time to implement Picos compatibility.  Implementing your
programming model elements in terms of the Picos interface may not always give
ideal results.  To address concerns such as those, a conscious effort has been
made to keep Picos as minimal and unopinionated as possible.

{2 Interoperability}

Picos is essentially an interface between schedulers and concurrent
abstractions.  Two phrases, {i Picos compatible} and {i Implemented in Picos},
are used to describe the opposing sides of this contract.

{3 Picos compatible}

The idea is that schedulers provide their own handlers for the Picos effects.
By handling the Picos effects a scheduler allows any libraries built on top of
the Picos interface to be used with the scheduler.  Such a scheduler is then
said to be {i Picos compatible}.

{3 Implemented in Picos}

A scheduler is just one element of a concurrent programming model.  Separately
from making a scheduler Picos compatible, one may choose to implement other
elements of the programming model, e.g. a particular approach to structuring
concurrency or a particular collection of communication and synchronization
primitives, in terms of the Picos interface.  Such scheduler agnostic elements
can then be used on any Picos compatible scheduler and are said to be {i
Implemented in Picos}.

{2 Design goals and principles}

The {{!Picos} core} of Picos is designed and developed with various goals and
principles in mind.

- {b Simple}: Picos should be kept as simple as possible.
- {b Minimal}: Picos should be kept minimal.  The dependency footprint should be
  as small as possible.  Convenience features should be built on top of the
  interface.
- {b Safe}: Picos should be designed with safety in mind.  The implementation
  must be data race free.  The interface should promote and always allow proper
  resource management.
- {b Unopinionated}: Picos should not make strong design choices that are
  controversial.
- {b Flexible}: Picos should allow higher level libraries as much freedom as
  possible to make their own design choices.

The documentation of the {{!Picos} concepts} includes design rationale for some
of the specific ideas behind their detailed design.

{3 Constraints Liberate, Liberties Constrain}

Picos aims to be unopinionated and flexible enough to allow higher level
libraries to provide many different kinds of concurrent programming models.
While it is impossible to give a complete list of what Picos does not dictate,
it is perhaps illuminating to explicitly mention some of those:

- Picos does not implement
  {{:https://en.wikipedia.org/wiki/Capability-based_security} capability-based
  security}.  Higher level libraries with or without capabilities may be built
  on top of Picos.
- Picos never cancels computations implicitly.  Higher level libraries may
  decide when cancelation should be allowed to take effect.
- Picos does not dictate which fiber should be scheduled next after a Picos
  effect.  Different schedulers may freely use desired data structures (queues,
  work-stealing deques, stacks, priority queues, ...) and, after handling any
  Picos effect, freely decide which fiber to run next.
- Picos does not dictate how fibers should be managed.  It is possible to
  implement both unstructured and structured concurrent programming models on
  top of Picos.
- Picos does not dictate which mechanisms applications should use for
  communication and synchronization.  It is possible to build many different
  kinds of communication and synchronization mechanisms on top of Picos
  including mutexes and condition variables, STMs, asynchronous and synchronous
  message passing, {{:https://en.wikipedia.org/wiki/Actor_model} actors}, and
  more.
- Picos does not dictate that there should be a connection between the scheduler
  and other elements of the concurrent programming model.  It is possible to
  provide those separately and mix-and-match.
- Picos does not dictate which library to use for IO.  It is possible to build
  direct-style asynchronous IO libraries on top of Picos that can then be used
  with any Picos compatible schedulers or concurrent programming models.

Let's build an incredible ecosystem of interoperable concurrent programming
libraries and frameworks!

{1 Conventions}

Many operation in the Picos libraries use
{{:https://en.wikipedia.org/wiki/Non-blocking_algorithm} non-blocking}
algorithms.  Unless explicitly specified otherwise,

- non-blocking operations in Picos are {i atomic} or {i strictly linearizable}
  (i.e. {{:https://en.wikipedia.org/wiki/Linearizability} linearizable} and
  {{:https://en.wikipedia.org/wiki/Database_transaction_schedule#Serializable}
  serializable}), and
- {{:https://en.wikipedia.org/wiki/Non-blocking_algorithm#Lock-freedom}
  lock-free} operations in Picos are designed to avoid having competing
  operations of widely different complexities, which should make such operations
  much less prone to starvation.