The code in the screenshot is different from the linked one. The screenshot code uses domains directly whereas the linked code uses domains lib.

It is also the case that the code spawns more than 8 domains? Both the recursive calls get passed with d - 1. Would showing the example with domainslib be too long? If so, what about a simple eio example?

I don't think we should direct users to a beta release in the up-and-coming instructions. A separate callout would be better.

Incidentally, I tend to use

opam switch create 5-latest --packages ocaml.5.0.0

in order to avoid hardcoding the ~release as that also gets rapidly out of date.

I would propose to have an Domainslib parallel loop as example rather than yet another Fibonacci's function with a double exponential slowdown. A parallel for (a vector addition maybe) seems to me both more recognizable and less subject to caveat.

Also the first beta will be labelled beta1: the alpha0 was supposed to be an exception and it leads to all kind of ordinal troubles: is beta0 the first beta release? the zeroth? What about beta1, would that be the first or second beta release?

I'm not entirely sure about using Domainslib in the code snippet.

On the one hand, I understand that we want to recommend users to use it instead of using the Domain API directly. So the code would be closer to what users would to see "in the wild".

On the other hand, the code snippet would then require installing domainslib to be run. Users who visit the site, copy the code and try it on a project or a REPL would get an error. And if they are new users, they will probably not know what to do with the cryptic Unbound module Domainslib error. That's not a great first-time experience.

I think it is probably better to add an instruction for installing domainslib in the OCaml 5 beta guide (and mention the possible error in such guide).

Do you mean that it would be acceptable to use Domainslib in the code snippet if we added instructions on how to install the opam package in the OCaml 5 beta announcement?

Yes, taking in account that installing the beta is not something that I expect new users to do without following some installation instructions, I think it would be fine to have some pointer for installing domainslib in those instructions.

The playground presumably can have domainslib?

Yes, taking in account that installing the beta is not something that I expect new users to do without following some installation instructions, I think it would be fine to have some pointer for installing domainslib in those instructions.

True, although I could imagine someone landing on the homepage, going to Get Started and installing OCaml 4.14, then trying to run the snippet.

Reading the announcement, installing OCaml 5 beta and trying to run the snippet is one path the user could take, but there are many more they could take which would ultimately lead to a confusing error if we use something else than the standard library in the code snippet.

Saying that I realize I'm arguing against the code I put in the PR: users would get an error because of the Domain module if they try to run the code after following the Get Started guide (which installs OCaml 4.14).

I guess if we really want to show code that uses Eio/Domainslib I could try and change the code snippet to tell users they need to follow a certain guide to be able to run the code, but I have a preference for a code snippet they would be able to run no matter the environment.

The playground presumably can have domainslib?

Wouldn't that depend on effects? (which the playground won't support since it's compiled with Jsoo)

I think that there is some unavoidable tension here between having a showcase snippet that works anywhere and a representative snippet that looks like some code that might be used in OCaml 5.

But maybe this is a sign that we don't want to switch the focus of the welcome code snippet? Looking at the current snippet, neither the square function nor the factorial function would benefit from using Domain for instance.

The playground presumably can have domainslib?

Wouldn't that depend on effects? (which the playground won't support since it's compiled with Jsoo)

Oops - I completely forgot about Domainslib's scheduler using effects 🤦

Looks like there are several good reasons not to include domainslib. If the playground is compiled with jsoo then even plain domain won't work, would it? JavaScript doesn't have parallelism.

I removed the parts that needed more discussion and only kept the banner for now, which links to the announcement post.

I'm happy to revisit the code snippet in a second time.