Fix mutex's docs inconsistency

[GuillaumeGomez]

Fixes #40176.

r? @steveklabnik
cc @rust-lang/docs

[ScottAbbey]

the mutex's lock will be unlocked.

I'm not sure this change is an improvement over the original. Shouldn't it match the language used in line 27:

ever accessed when the mutex is locked.

[sfackler]

I agree - a mutex doesn't contain a lock, it is a lock, IMO.

[ScottAbbey]

Acquires a mutex, blocking

Two lines after this, the comment speaks of acquiring "the lock," should this instance be modified as well?

[whoisj]

Concern here: "lock" is generic, while "mutex" is shorthand for "mutually exclusive lock" and therefore seems most specific and correct to me.

[ScottAbbey]

This is the same paragraph directly quoted in #40176, would you say it would have been better to change the one instance of "the lock" to "the mutex" instead of the other way around?

[whoisj]

Yes "lock" or "acquire" as the verb, and "mutex" as the noun. Therefore "the mutex" makes more sense than "the lock". 😃

[GuillaumeGomez]

I agree with @ScottAbbey on this one. For non-english speaker, acquiring a lock better than acquiring a mutex which doesn't mean much.

[whoisj]

@GuillaumeGomez while I agree, this isn't just pros. We're discussing technical documentation and as such should be as specific as possible, without being exclusionary.

If we're going with the general term, then we need to the MSDN thing of explaining that the lock is exclusive and will block any threads that attempt to acquire the lock while the lock is held.

IMO this gets verbose, but does have the advantage of being very approachable and lends itself well to education as well as to translation.

[frewsxcv]

cc @rust-lang/libs for terminology here

[alexcrichton]

I personally consider "mutex" and "lock" as interchangeable, but canonicalizing on one seems fine (e.g. they're interchangeable, so doesn't matter what we call it!)

[ScottAbbey]

I agree with @whoisj, almost every reference to "lock" should instead be "mutex."

The language that seems to make the most sense is:

The mutex may be locked or unlocked.

The original complaint in #40176 was that the lock and the mutex were both used to refer to the Mutex object. By changing all references of "mutex" to "lock", the problem only got worse, now we are talking about locking and unlocking the lock.

Searching for some other published writing about a similar topic, I found the following in Chapter 30 (page 634) of The Linux Programming Interface, by Michael Kerrisk:

When a thread locks a mutex, it becomes the owner of that mutex. Only the mutex owner can unlock the mutex.

I find this short quote easy to read and understand. Rewriting that sentence to fit the state of this mutex documentation as it currently stands, we would have something like:

When a thread acquires a lock, it becomes the holder of that lock. Only the lock owner can unlock the mutex.

This is still in the same confusing state we started with. Shouldn't the thread acquire (or lock) "the mutex", be the holder (or owner) of "the mutex", and "the mutex holder (or owner)" be able to unlock it?

There are still some consistency issues. In the comment for is_poisoned:

/// Determines whether the lock is poisoned
...
/// panic!(); // the mutex gets poisoned

The first one and several other "lock is poisoned" references should instead say "the mutex".

This phrase appears many times:

/// If another user of this mutex panicked while holding the lock, then this call will return an error instead.

I think all of those should be changed back to "while holding the mutex".

Under struct Mutex<T>:

to ensure that the native mutex is used correctly we box the inner lock...

Should be "the inner mutex".

I don't trust myself to try writing any of this as I really don't know what I'm talking about anyway.

[steveklabnik]

agree wholeheartedly with @ScottAbbey

[steveklabnik]

@GuillaumeGomez ping! any updates on this?

[GuillaumeGomez]

I need to update it. Will do it in the day.

[GuillaumeGomez]

Ok so I made a first update. Did I miss anything?

[steveklabnik]

a couple more spots, then r=me

[steveklabnik]

this is the inverse

[steveklabnik]

same

[steveklabnik]

same

[steveklabnik]

same on both lines

[steveklabnik]

same

[GuillaumeGomez]

I updated to @steveklabnik's comments.

[steveklabnik]

@bors: r+ rollup

[bors]

📌 Commit e7c2160 has been approved by steveklabnik