Consider document the memory ordering of `Semaphore`

[ADD-SP]

The semaphore does provide the necessary orderings, and it's not something that's going to change. That said, it could make sense to mention this in the documentation.

Originally posted by @Darksonn in #7418 (comment)

[ADD-SP]

In the current implementation, Semaphore::acquire.await and Semaphore::close provides Release-Acquire ordering.

All memory writes that happened-before the Semaphore::close become visible side-effects in any thread who gets AcquireError while polling the Semaphore::acquire.await.

Now, I'm thinking about how to describe this behavior in the official document, but this is not easy.

In semantic speaking, Semaphore::acquire.await plus Semaphore::close looks not like something that provides Release-Acquire ordering, and doing synchronization using these two method is not a usual use case, so we need to use carefully prepared wording, otherwise this will not only not help the reader to understand, but also confuses them.

@Darksonn Do you have any idea about wording?

[Darksonn]

I think we can say that the semaphore has the same synchronization properties as operations on a single atomic with the following orderings:

• Successfully acquiring a permit is an AcqRel operation.
• Adding a permit is an AcqRel operation.
• Forgetting permits is an AcqRel operation.
• Closing the semaphore is an AcqRel operation.
• Failure to acquire a permit because the semaphore is empty behaves like an Acquire load.
• Failure to acquire a permit because the semaphore is closed behaves like an Acquire load.
• The methods available_permits and is_closed behaves like an Acquire load.

With the caveat that calling wake on wakers happens after changing the state of the semaphore in a non-atomic manner.