[Caml-list] Human-friendly Lwt: documenting and refactoring the Lwt core

[Caml-list] Human-friendly Lwt: documenting and refactoring the Lwt core

[Anton Bachin]

Greetings everyone,

Lwt is making an effort to become more reader- and contributor-friendly.

  https://github.com/ocsigen/lwt/pull/354


To summarize, from the PR: the core, lwt.ml, has been reorganized to
make it more readable. It has been equipped with thorough comments,
including a friendly overview of all concepts used by the core.

We hope this change opens Lwt up to more contributions of all kinds. It
should unblock major upcoming work, such as porting Lwt to multicore
effects. Understanding Lwt better also makes it possible to write the
much-promised new manual.

The new Lwt core is meant to be a permanent work in progress: if you
don't understand it, or find that something in it is *still* written in
a confusing way, please ask/let the Lwt maintainers know. We *want* to
help readers understand, and to improve that code! And, anyway, your
query will very likely teach *us* something.


Any review of the PR would be very helpful, to Lwt and to all of its
users – even if you read only to find typos. Also, if you have access to
a stress test, it would be very useful to put the refactored core
through the paces. There are instructions at the bottom of the PR. If
the stress test is open source, maybe we can use it as a guide for
writing a stress test specifically for Lwt, because Lwt really needs to
have at least one of those.


Happy concurrent programming,
Anton