dotnet / dotnet/dotnet-api-docs
Mutex constructor documentation contradicts itself
- Dominant language
- C#
- Stars
- 949
- Forks
- 1.7k
- Avg merge
- 3d 27m
- Merged PRs (30d)
- 49
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
### Article author
@dotnet-bot
Contributor guide
Assessment
This issue has not been assessed yet.