document reentrancy of `std::sync::Mutex`.

[matklad]

std::sync::Mutex is not reentrant (you can't .lock a mutex if you already .locked it and haven't released the lock), but this behavior is not documented.

Looks like the exact consequences of locking the mutex twice vary by platform. On linux, you get a deadlock. On windows there is a panic: https://github.com/rust-lang/rust/blob/master/src/libstd/sys/windows/mutex.rs#L75. Maybe this should panic on all platforms?

[alexcrichton]

Windows will also deadlock most of the time as we use SRWLOCK instead of CRITICAL_SECTION, it should basically be documented that you can't lock a mutex twice on the same thread.

[matklad]

it should basically be documented that you can't lock a mutex twice on the same thread.

But are the exact consequences of locking twice unspecified?

[alexcrichton]

Yeah I think we'll want to leave it unspecified. We must detect it with CRITICAL_SECTION as the underlying primitive allows reentrancy, and the most reasonable thing to do there is to just panic. We'd probably panic if we could on SRWLOCK and pthread_mutex_t, but they're not as easily detectable.

[havelund]

The problem is that Rust is so paranoid about data races, that one has to uses mutexes all over the place (if using shared memory) to fight the borrow checker off. This results then in increased risk of deadlocks due to the fact that locks are not reentrant.

[raindev]

@havelund parking_lot crate provides reentrant mutex if you need it:
https://amanieu.github.io/parking_lot/parking_lot/struct.ReentrantMutex.html

I‘m curious what’re the reasons behind not providing reentrant mutex as the default implementation in the standard library?

[Ixrec]

I think it's because Mutex and friends were originally meant to be wrappers around the native OS synchronization primitives, and some OS mutexes are not reentrant, though I'm not 100% sure on that.

[matklad]

@havelund @raindev @Ixrec, there's definitely an interesting conversation to have here, but a closed PR is not the right venue for such discussions:

• it's unlikey to be noticed by anyone not originally subscribed to the issue
• it actively pings all relevant folks, which spends people's time.

I've moved this issue to the forum: https://users.rust-lang.org/t/reentrant-mutexes-in-rust/35653

In the future, please consider steering folks to the appropriate discussion platforms, rather then engaging in the conversation on GitHub :)

Thanks!