Description
Type of issue
Other (describe below)
Description
Regarding documentation for the Mutex(Boolean, String, Boolean) constructor overload:
There is confusion about the functionality of the third parameter.
The summary for that overload at the top of page states:
Initializes a new instance of the Mutex class with a Boolean value that indicates whether the calling thread should have initial ownership of the mutex, a string that is the name of the mutex, and a Boolean value that, when the method returns, indicates whether the calling thread was granted initial ownership of the mutex.
The same information in the summary is repeated at the beginning of the detail section for the Mutex(Boolean, String, Boolean) overload
However, the following example is then provided in the detail section:
public Mutex(bool initiallyOwned, string? name, out bool createdNew);
And the following description is provided for the third parameter
createdNew Boolean
When this method returns, contains a Boolean that is true if a local mutex was created (that is, if name is null or an empty string) or if the specified named system mutex was created; false if the specified named system mutex already existed. This parameter is passed uninitialized.
So does the value of the third parameter indicate whether the calling thread was granted ownership the mutex or whether a new mutex was created? For example, when a mutex named "MyMutex" does not already exist and the following code is run:
bool requestInitialOwnership = false;
string mutexName = "MyMutex";
bool mutexWasCreated;
Mutex m = new Mutex(requestInitialOwnership,
"MyMutex",
out mutexWasCreated);
What is the value of mutexWasCreated?
The summary documentation indicates that it should be false (because requestInitialOwnership is false), but the example documentation indicates that it should be true (because a new mutex was created).
This contradiction appears in the documentation for all .Net and .Net Framework versions that I have checked starting with .Net Framework 1.1
Page URL
https://learn.microsoft.com/en-us/dotnet/api/system.threading.mutex.-ctor?view=net-9.0
Content source URL
https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Threading/Mutex.xml
Document Version Independent Id
76ae6db6-98c6-6a17-fc8d-5391b7bb5d06
Platform Id
eb82dadc-d5aa-e50f-3a5a-e7075dfb5d5e