From 0f1bea6f5364bda128f40786fa64f52a8cebdda4 Mon Sep 17 00:00:00 2001 From: Thomas Leonard Date: Wed, 8 Mar 2023 10:10:04 +0000 Subject: [PATCH] Mention eio_posix in the documentation Needed for #456. --- HACKING.md | 30 +++++++++++++++++++++++++++++- README.md | 4 +++- 2 files changed, 32 insertions(+), 2 deletions(-) diff --git a/HACKING.md b/HACKING.md index bcfdf8768..53f1ee112 100644 --- a/HACKING.md +++ b/HACKING.md @@ -32,9 +32,37 @@ Most backends are built in two layers: - A "low-level" module directly wraps the platform's own API, just adding support for suspending fibers for concurrency and basic safety features (such wrapping `Unix.file_descr` to prevent use-after-close races). -- An implementation of the cross-platform API defined in the `eio` package that uses the low-level API internally. +- An implementation of the cross-platform API (as defined in the `eio` package) that uses the low-level API internally. This should ensure that errors are reported using the `Eio.Io` exception. +`eio_posix` is the best one to look at first: + +- `lib_eio_posix/sched.ml` is similar to the mock scheduler, but extended to interact with the OS kernel. +- `lib_eio_posix/low_level.ml` provides fairly direct wrappers of the standard POSIX functions, + but using `sched.ml` to suspend and resume instead of blocking the whole domain. +- `lib_eio_posix/net.ml` implements the cross-platform API using the low-level API. + For example, it converts Eio network addresses to Unix ones. + Likewise, `fs.ml` implements the cross-platform file-system APIs, etc. +- `lib_eio_posix/eio_posix.ml` provides the main `run` function. + It runs the scheduler, passing to the user's `main` function an `env` object for the cross-platform API functions. + +When writing a backend, it's best to write the main loop in OCaml rather than delegate that to a C function. +Some particular things to watch out for: + +- If a system call returns `EINTR`, you must switch back to OCaml + (`caml_leave_blocking_section`) so that the signal can be handled. Some C + libraries just restart the function immediately and this will break signal + handling (on systems that have signals). + +- If C code installs a signal handler, it *must* use the alt stack (`SA_ONSTACK`). + Otherwise, signals handlers will run on the fiber stack, which is too small and will result in memory corruption. + +- Effects cannot be performed over a C function. + So, if the user installs an effect handler and then calls a C mainloop, and the C code invokes a callback, + the callback cannot use the effect handler. + This isn't a problem for Eio itself (Eio's effect handler is installed inside the mainloop), + but it can break programs using effects in other ways. + ## Tests Eio has tests in many places... diff --git a/README.md b/README.md index b75c57a62..065ff04bc 100644 --- a/README.md +++ b/README.md @@ -91,10 +91,11 @@ See [Awesome Multicore OCaml][] for links to work migrating other projects to Ei ## Structure of the Code - [Eio][] provides concurrency primitives (promises, etc.) and a high-level, cross-platform OS API. +- [Eio_posix][] provides a cross-platform backend for these APIs for POSIX-type systems. - [Eio_luv][] provides a cross-platform backend for these APIs using [luv](https://github.com/aantron/luv) (libuv). - [Eio_linux][] provides a Linux io-uring backend for these APIs, plus a low-level API that can be used directly (in non-portable code). -- [Eio_main][] selects an appropriate backend (e.g. `eio_linux` or `eio_luv`), depending on your platform. +- [Eio_main][] selects an appropriate backend (e.g. `eio_linux`, `eio_posix` or `eio_luv`), depending on your platform. ## Getting OCaml 5.0 @@ -1730,6 +1731,7 @@ Some background about the effects system can be found in: [Eio.Domain_manager]: https://ocaml-multicore.github.io/eio/eio/Eio/Domain_manager/index.html [Eio.Promise]: https://ocaml-multicore.github.io/eio/eio/Eio/Promise/index.html [Eio.Stream]: https://ocaml-multicore.github.io/eio/eio/Eio/Stream/index.html +[Eio_posix]: https://github.com/ocaml-multicore/eio/blob/main/lib_eio_posix/eio_posix.mli [Eio_luv]: https://ocaml-multicore.github.io/eio/eio_luv/Eio_luv/index.html [Eio_linux]: https://ocaml-multicore.github.io/eio/eio_linux/Eio_linux/index.html [Eio_main]: https://ocaml-multicore.github.io/eio/eio_main/Eio_main/index.html