The API itself is split in two main parts: the “Concurrency primitives” and the “Cross-platform OS API”. However, the backends tend to combine them. For example the Eio_luv backend runs a libuv event loop, which works with libuv abstractions such as Luv.File. You can’t use a Luv.File with an io_uring event loop, for example, so the event loop also implements the OS abstractions.
Each backend is designed for some platform (Linux, macos, Windows, libuv, etc), and should provide an API for whatever that platform provides. Then there is a standard set of types that common operating systems provide, and Eio_main can select one of the backends that implements this common set.
However, there will also be other backends that don’t implement all of the suggested interfaces. For example, an Eio_browser.run wouldn’t provide a file-system (and browser code wouldn’t use Eio_main).
Some backends won’t implement any of the interfaces. For example, an Eio_xen.run would only provide low-level Xen APIs (allowing sharing of pages of memory with other VMs and sending inter-Xen-domain interrupts). Then OCaml libraries would be used to build OS abstractions on top (such as Ethernet devices, IP networking, block devices, file-systems). Ideally, these higher-level abstractions would implement the standard Eio interfaces and would therefore be compatible with other Eio code.
The exact APIs are very much up for debate, and will combine features from Mirage, the stdlib, Lwt and other platforms.
Taking the sole example of fibers, I would certainly like to see a core set of effects/primitives to deal with them in the
Stdlibbut in a way that allows me to interpret them in possible different ways than is exposed here.
The ones Eio uses itself are here: Effects (eio.Eio.Private.Effects). Something like this could go in the stdlib one day. The main opinionated item in this API is support for cancellation.