Add documentation to `Send` & `Sync` impls

[IoaNNUwU]

Location

rust/library/std/src/sync/mutex.rs

Lines 186 to 189 in 0ad927c

	#[stable(feature = "rust1", since = "1.0.0")]
	unsafe impl<T: ?Sized + Send> Send for Mutex<T> {}
	#[stable(feature = "rust1", since = "1.0.0")]
	unsafe impl<T: ?Sized + Send> Sync for Mutex<T> {}

Summary

I think it is a good idea to document Send & Sync impls in types such as Mutex, RwLock etc. especially considering they are unsafe traits.

Also it's not obvious why some types have particular restrictions, for example:

• why Mutex is Sync only if the T: Send
• why MutexGuard is !Send

It can be done as // SAFETY comments or proper docs.

[workingjubilee]

for Mutex in particular, elsewhere we document:

/// A mutual exclusion primitive useful for protecting shared data
///
/// This mutex will block threads waiting for the lock to become available. The
/// mutex can be created via a [`new`] constructor. Each mutex has a type parameter
/// which represents the data that it is protecting. The data can only be accessed
/// through the RAII guards returned from [`lock`] and [`try_lock`], which
/// guarantees that the data is only ever accessed when the mutex is locked.
///

this makes the Mutex safety docs for these unsafe impls slightly tautological: "why is this Sync? because we guarantee threads are blocked until they get the lock, thus taking care of data races. why do we block and make people wait? to make this soundly Sync. why must it be Send to be Sync? because if it's not Send, it's not capable of being accessed safely from multiple threads at all."

so it's mostly organizing data already there into something nicely written. bikeshed prone, but """easy""" (if you are a decent writer).

[workingjubilee]

I suppose that is possibly not easy. 🤔 subjective.

[IoaNNUwU]

Sync doc states:

Types for which it is safe to share references between threads.

I would assume that Mutex is Sync regardless of T boundries, because we cannot get unprotected access to inner structure and can only access it using lock() method by single thread at the time. So it should be safe to share for example &'static Mutex<T> between threads regardless of T being Send.

Also I do understand the problem. We cannot have, for example Arc<Mutex<Rc<T>>> (Rc is not Send) because Rc<T> is not-thread-safe reference-like structure that wraps pointer to heap allocated RcInner<T> and enables non-atomic reference counting, so other copies of Rc are unprotected.

I think it is a good idea to add this example in some place:

• Sync doc
• Send doc
• Mutex doc
• impl Sync for Mutex

Also Sync & Send docs can be improved adding notion of Reference-like structures and why we can think of implementing Send on them is like implementing Sync on the inner structure. I think with this knowledge trait bounds on Send & Sync impls for Mutex are obvious and docs on these impls could link to Send & Sync docs.

[Psalmuel01]

i would like to pick this up, and improve the docs

[workingjubilee]

@Psalmuel01 Go for it!

[Psalmuel01]

you didnt assign to me yet. ive worked on it, do i just go ahead and create a pr