Description Allan Pratt 2005-06-02 22:04:06 EDT

The RAC exports a platform-independent API for managing critical sections 
(mutexes): ra_mutexCreate, ra_mutexEnter, ra_mutexExit, and ra_mutexDestroy.

The details of the mutexes you get when you use these functions are not 
documented, and their behavior changes from one platform to another.

Specifically, on Windows, if a thread has already entered a mutex and tries to 
enter it again, it will succeed. That thread will own the mutex until it exits 
as many times as it entered. This is known as a "reentrant" mutex.

On Linux, a thread will block forever if it tries to enter a mutex that it has 
already entered. This is "non-reentrant."

Both styles are perfectly reasonable ways to implement mutexes, but the 
component exporting the API (in this case, the RAC) needs to specify which kind 
it creates, so clients can use them properly. In this case, with the lack of 
other RAC documentation, I think the comments in RAComm.h are the best place to 
describe these details.

It is safe to document one's mutexes as "non-reentrant" even if they are 
reentrant on some platforms: as long as clients know they can not rely on 
reentrant behavior, it doesn't matter if the mutexes are actually reentrant. 
The opposite is not true.

Another implementation detail that must be specified in the API documentation 
is whether a thread that creates a mutex automatically owns it, or must enter 
it once in order to own it. Without knowing this, people can't reliably write 
clients of your API. In this case there is no "common denominator": you have to 
pick one, document it, and make sure your implementation behaves in the way you 
decided on all platforms.

So: to fix this bug, please add these comments to RAComm.h in the RAC sources, 
in the block comment above ra_mutexCreate:

 * The mutex is non-reentrant: a thread will block if it has already
 * entered the mutex and tries to enter it again.
 *
 * When ra_mutexCreate returns, no thread owns the mutex.

Also add words to that effect to other pertinent RAC documentation, if there is 
any.