blog.osau.re

MirageOS and OCaml stuffs.
Back to index

Miou, retrospective (1), API

After two years of developing Miou, I am starting a series of articles to talk about this project, my retrospective view of it in relation to the community, and the issues that arose during Miou's development.

In addition, this article will focus mainly on the API and how Miou can actually be more interesting to use than its competitors such as Eio.

All of this stems, of course, from a certain vision (influenced by opinion) of how a library should evolve and develop, but it is interesting to explore the question of the API and understand why Miou offers a different interface. We may not all agree, but clarifying the choices (in the comments or via articles) is always interesting.

The scheduler as the common factor in all applications

Before commenting on the API work we have done on Miou, we need to frame the issue (and this is perhaps the most important thing), because bad questions inevitably produce bad answers. We need to understand "what we are talking about when we propose a scheduler".

The purpose of a language-level scheduler is to manage concurrency within the application runtime, rather than relying on the operating system. This approach allows tasks — especially I/O-bound ones — to yield and resume efficiently in user space, avoiding the overhead of system-level thread switching.

The most difficult part of developing an application

When developing an application, we build on top of an existing API — often the POSIX API — which defines how we interact with the underlying system.

What’s often underestimated is that each syscall is not just a function call — it interacts with the language's own concurrency model and scheduler. Whether you're using threads, async/await, green threads, or effect handlers, every syscall implies a point where control may be yielded or blocked. This implicit scheduling makes reasoning about program flow significantly harder.

Many bugs stem from misunderstandings of these interactions — especially when the behavior depends on both the system's response and the language's runtime decisions. Since much of this is poorly documented or deeply hidden in implementation details, developers are often left to rely on sparse man(1) pages or trial and error.

The key takeaway: system calls aren't just about the system — they're deeply tied to your language's runtime and scheduler, and that hidden layer of complexity is one of the hardest things to master in application development.

Using a scheduler means giving in to a way of programming

Finally, the last point to clarify before strictly speaking about the API is that wanting to use Miou fundamentally means agreeing to programme in OCaml in a certain way.

Even though we can talk about APIs and what a scheduler exposes, a certain amount of experience with a scheduler (such as lwt) will inevitably lead you to structure your application according to the behaviour of that scheduler.

And that's when you realise that the constraint of developing in a certain way according to the scheduler does not strictly stem from its API and what the library can expose, but rather from implementation details that are the source of a wide variety of bugs.

Historically, we have already seen trends arising from the best of intentions that have ultimately led to acceptance of this fact: coding an application with async is fundamentally different from coding an application with lwt.

The expert might retort: but these two schedulers use the continuation monad, they share the same interface. Others will go further by mentioning the idea that one could functorise in order to reuse, for example, an implementation of the HTTP protocol for these two schedulers!

The maintainer and author of certain libraries would tell you from experience that such a solution (which could be replaced by variants, or another mechanism allowing an implementation to be injected according to an interface) would only end up in a dead end.

Inter-compatibility between schedulers, a gentle discourse

This sub-section is mainly intended to deconstruct a discourse that I have heard over the past two years, namely the possible intercompatibility between schedulers using a beautiful interface or common elements that can be reused by other schedulers. At this stage, the idea may be interesting, especially since on the other side of the fence such an ambition has been realised with std::async.

However, this discourse unfortunately went further in suggesting that an application developed with such common elements could magically work on multiple schedulers (provided that the latter reuse these common elements).

Unfortunately, crossing the Rubicon and building such an imaginary world means (consciously or not) omitting a reality that I have just explained above: the details of implementation.

Indeed, all the subtleties that may exist between schedulers cannot be described solely with the OCaml language. There are side effects everywhere... and it is difficult to imagine, at a certain point, that an application could run well and more or less in the same way with two differently implemented schedulers.

I mentioned that historically this attempt has been made, and this is indeed the case with [lwt-async][lwt-async]. Do you remember the common interface? Another example is CoHTTP and the [impossible attempt][S.IO] to bring two different worlds together. It's all the more frustrating when you see what one scheduler can offer and the other can't... It is even more frustrating when you can only find common ground between POSIX and what a unikernel can offer us (farewell, sendfile(2)).

There are possibilities, but they will be discussed in more detail in another article as they are not only intrinsic to API work.

The real problem with a scheduler

It can actually be described as follows: a scheduler has one objective, which is to manage tasks. In the implementation of these tasks, we will surely find syscalls (with all their subtleties depending on the system, its version and the man(1), since we can only observe them as black boxes). And this mix between task management and interactions with the system fundamentally imposes a certain method in the development of an application based on implementation details.

When developing with lwt, we build a mental model that cannot be the same as that of async (even though we can find the same monadic interface in it).

This model allows us to imagine the behaviour of the scheduler and establish axioms. And these axioms will then be fundamentally necessary for us to interact with the system (yes, I can use this buffer and transmit it to the system because I know that the scheduler will ensure my exclusive access to it!).