Document caml_domain_alone

[gasche]

While working on #13950, @OlivierNicole asked whether caml_domain_alone () sequential fast paths are really correct.

      if (caml_domain_alone()) {
        // sequential fast path
        ...
      } else {
        // slower concurrent version
        ...
      }

Olivier asked: what if a new domain somehow gets spawned during the sequential fast path?

After thinking more about this, I conclude that it is in fact not possible for a new domain to start during a caml_domain_alone() critical section.

Intuitively this is guaranteed by the fact that if we hold the domain lock, and if we don't call caml_domain_spawn ourselves in the critical section, then no one else is around to call it either so no new domain can start. But in practice the reasoning is a bit delicate.

Commits

In the first commit, I document this assumption and try my best to explain why I believe that it currently holds, in trunk. There is a subtlety, which is that some domain initialization code runs after the new domain gets the domain lock, but before caml_num_domains_running is incremented (caml_domain_alone() is caml_num_domains_running == 1). This initialization code could contain sequential fast paths protected by caml_domain_alone() for sequential fast paths, but this should be okay because the only other domain running is the parent domain, and the parent domain is waiting on the child domain (and listening to the void for STW requests).

In the second commit, I remove the subtlety by making sure that a spawning domain increments caml_num_domains_running right after acquiring its own domain lock, so that the domain-initialization code never observes caml_domain_alone (). This makes the reasoning about the correctness of caml_domain_alone () much simpler.

cc @OlivierNicole and maybe @stedolan, @NickBarnes.

[kayceesrk]

The change looks good to me.

Incrementing caml_num_domains_running right after the domain lock is obtained is also sensible. In a sense, caml_domain_alone may always return false, and the program will remain correct. The change makes it return false a tiny bit earlier, simplifying assumptions.

[ghost]

Appears to be correct.

[gasche]

Thanks all! Merging now.

[OlivierNicole]

Thank you for the explanation!

For future reference: there was a small mishap in that a line suppression that should have been part of the second commit ended up as part of the first commit.