Improve docs for Fiber::ExecutionContext

[ysbaddaden]

An attempt to improve the API docs for execution contexts a bit. Improve readability, link to Sync and fix a few potentially confusing phrases.

[bcardiff]

I think we can also add, if not present, something about how EC are allocated in system threads and how these are setup.

A couple of questions that arise:

I assume that Isolated is pinned to a system thread, but I am not sure if that holds for concurrent.

In parallel, do have a way to configure the affinity?

Do execution context share system threads? I assume they don't.

[ysbaddaden]

The wording has been chosen to focus on the guarantees of how the fibers will run (that won't change), not how they are related to system threads (implementation detail, will change).

In #15885 we start to decouple schedulers and threads — similar to how Go decouples P from M, where a Processor (scheduler) can run on any Machine (system thread). It allows to reuse system threads across execution contexts.

Starting with #15871 Concurrent isn't guaranteed to keep running on the same thread. Some blocking syscalls (e.g. getaddrinfo) may move the scheduler to another system thread. The guarantee is that the fibers will always run concurrently to each other.

The one exception is the Isolated context where the fiber is guaranteed to own the system thread.

In any case, a thread will be reused to reattach a scheduler (isolated, concurrent or parallel).

The documentation of each type should be explicit about its guarantees (the general intro on ExecutionContext isn't). Maybe they should also explicit what to expect and what not to expect in terms of threads.

[bcardiff]

I understand focusing on guarantees and not on implementation details. But some language features like ThreadLocal require a deeper understanding due to abstraction leak.

[ysbaddaden]

Let's keep it as DRAFT. We can keep improving 💪