Add a note comparing against std types

[notgull]

Closes #57

[taiki-e]

async-lock will actually just use std::sync::Mutex under the hood if the std feature is enabled

For Mutex, the lock fast path is a single CAS. event-listener used in slow path uses std mutex internally, but it would be different from "just use std::sync::Mutex under the hood".

async-lock/src/mutex.rs

Lines 358 to 360 in 604d461

	if this.acquire_slow.is_none() {
	match this.mutex.try_lock() {
	Some(guard) => return Poll::Ready(guard),

async-lock/src/mutex.rs

Lines 160 to 166 in 604d461

	pub fn try_lock(&self) -> Option<MutexGuard<'_, T>> {
	if self
	.state
	.compare_exchange(0, 1, Ordering::Acquire, Ordering::Acquire)
	.is_ok()
	{
	Some(MutexGuard(self))

[notgull]

For Mutex, the lock fast path is a single CAS. event-listener used in slow path uses std mutex internally, but it would be different from "just use std::sync::Mutex under the hood".

Good point, I've clarified this by saying that it's part of the notification mechanism.

[taiki-e]

you should

Personally, I do not believe that the benefits of using std::sync or parking_lot here necessarily exceed the risk of accidentally holding the guard across the await point.

Especially when using parking_lot, it is easy to make that mistake because of the send guard. (I recently saw a colleague make that mistake and spend hours debugging.)

[notgull]

Personally, I do not believe that the benefits of using std::sync or parking_lot here necessarily exceed the risk of accidentally holding the guard across the await point.

For standard library mutexes, there is a Clippy lint nowadays that prevents this scenario from happening. I've made the language less impactful, but I still think this isn't as large of an issue

[Jules-Bertholet]

Maybe link to the Clippy lint? https://rust-lang.github.io/rust-clippy/stable/index.html#/await_holding_lock

[notgull]

Good idea, I've added this

[Jules-Bertholet]

This is quite repetitive, I think we can have something much shorter. For example, you could extend the sentence on line 19 to If you already use libstd and you aren't holding locks across await points (there is a [Clippy lint](link) to check for this), you should consider std::sync instead of this crate.

[notgull]

Amended this

[Jules-Bertholet]

tokio::sync have their own version of this notice, which may provide inspiration.