Type of issue

Other (describe below)

Description

Regarding documentation for theMutex(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 theMutex(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 istrue 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 befalse (because requestInitialOwnership is false), but the example documentation indicates that it should betrue (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

Article author

@dotnet-bot