dotnet / dotnet/dotnet-api-docs

Mutex constructor documentation contradicts itself

Open
#11,546 1 comment 0 reactions 0 assignees View on GitHub
area-System.Threading untriaged
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.