Change:
//! Useful synchronization primitives. //! <del> //! This module contains useful safe and unsafe synchronization primitives. //! Most of the primitives in this module do not provide any sort of locking //! and/or blocking at all, but rather provide the necessary tools to build //! other types of concurrent primitives. </del> <ins> //! ## The need for synchronization //! //! Conceptually, a Rust program is a series of operations which will //! be executed on a computer. The timeline of events happening in the //! program is consistent with the order of the operations in the code. //! //! Consider the following code, operating on some global static variables: //! //! ```rust //! static mut A: u32 = 0; //! static mut B: u32 = 0; //! static mut C: u32 = 0; //! //! fn main() { //!     unsafe { //!         A = 3; //!         B = 4; //!         A = A + B; //!         C = B; //!         println!("{} {} {}", A, B, C); //!         C = A; //!     } //! } //! ``` //! //! It appears as if some variables stored in memory are changed, an addition //! is performed, result is stored in `A` and the variable `C` is //! modified twice. //! //! When only a single thread is involved, the results are as expected: //! the line `7 4 4` gets printed. //! //! As for what happens behind the scenes, when optimizations are enabled the //! final generated machine code might look very different from the code: //! //! - The first store to `C` might be moved before the store to `A` or `B`, //!   _as if_ we had written `C = 4; A = 3; B = 4`. //! //! - Assignment of `A + B` to `A` might be removed, since the sum can be stored //!   in a temporary location until it gets printed, with the global variable //!   never getting updated. //! //! - The final result could be determined just by looking at the code //!   at compile time, so [constant folding] might turn the whole //!   block into a simple `println!("7 4 4")`. //! //! The compiler is allowed to perform any combination of these //! optimizations, as long as the final optimized code, when executed, //! produces the same results as the one without optimizations. //! //! Due to the [concurrency] involved in modern computers, assumptions //! about the program's execution order are often wrong. Access to //! global variables can lead to nondeterministic results, **even if** //! compiler optimizations are disabled, and it is **still possible** //! to introduce synchronization bugs. //! //! Note that thanks to Rust's safety guarantees, accessing global (static) //! variables requires `unsafe` code, assuming we don't use any of the //! synchronization primitives in this module. //! //! [constant folding]: https://en.wikipedia.org/wiki/Constant_folding //! [concurrency]: https://en.wikipedia.org/wiki/Concurrency_(computer_science) //! //! ## Out-of-order execution //! //! Instructions can execute in a different order from the one we define, due to //! various reasons: //! //! - The **compiler** reordering instructions: If the compiler can issue an //!   instruction at an earlier point, it will try to do so. For example, it //!   might hoist memory loads at the top of a code block, so that the CPU can //!   start [prefetching] the values from memory. //! //!   In single-threaded scenarios, this can cause issues when writing //!   signal handlers or certain kinds of low-level code. //!   Use [compiler fences] to prevent this reordering. //! //! - A **single processor** executing instructions [out-of-order]: //!   Modern CPUs are capable of [superscalar] execution, //!   i.e. multiple instructions might be executing at the same time, //!   even though the machine code describes a sequential process. //! //!   This kind of reordering is handled transparently by the CPU. //! //! - A **multiprocessor** system executing multiple hardware threads //!   at the same time: In multi-threaded scenarios, you can use two //!   kinds of primitives to deal with synchronization: //!   - [memory fences] to ensure memory accesses are made visibile to //!   other CPUs in the right order. //!   - [atomic operations] to ensure simultaneous access to the same //!   memory location doesn't lead to undefined behavior. //! //! [prefetching]: https://en.wikipedia.org/wiki/Cache_prefetching //! [compiler fences]: crate::sync::atomic::compiler_fence //! [out-of-order]: https://en.wikipedia.org/wiki/Out-of-order_execution //! [superscalar]: https://en.wikipedia.org/wiki/Superscalar_processor //! [memory fences]: crate::sync::atomic::fence //! [atomic operations]: crate::sync::atomic //! //! ## Higher-level synchronization objects //! //! Most of the low-level synchronization primitives are quite error-prone and //! inconvenient to use, which is why the standard library also exposes some //! higher-level synchronization objects. //! //! These abstractions can be built out of lower-level primitives. //! For efficiency, the sync objects in the standard library are usually //! implemented with help from the operating system's kernel, which is //! able to reschedule the threads while they are blocked on acquiring //! a lock. //! //! The following is an overview of the available synchronization //! objects: //! //! - [`Arc`]: Atomically Reference-Counted pointer, which can be used //!   in multithreaded environments to prolong the lifetime of some //!   data until all the threads have finished using it. //! //! - [`Barrier`]: Ensures multiple threads will wait for each other //!   to reach a point in the program, before continuing execution all //!   together. //! //! - [`Condvar`]: Condition Variable, providing the ability to block //!   a thread while waiting for an event to occur. //! //! - [`mpsc`]: Multi-producer, single-consumer queues, used for //!   message-based communication. Can provide a lightweight //!   inter-thread synchronisation mechanism, at the cost of some //!   extra memory. //! //! - [`Mutex`]: Mutual Exclusion mechanism, which ensures that at //!   most one thread at a time is able to access some data. //! //! - [`Once`]: Used for thread-safe, one-time initialization of a //!   global variable. //! //! - [`RwLock`]: Provides a mutual exclusion mechanism which allows //!   multiple readers at the same time, while allowing only one //!   writer at a time. In some cases, this can be more efficient than //!   a mutex. //! //! [`Arc`]: crate::sync::Arc //! [`Barrier`]: crate::sync::Barrier //! [`Condvar`]: crate::sync::Condvar //! [`mpsc`]: crate::sync::mpsc //! [`Mutex`]: crate::sync::Mutex //! [`Once`]: crate::sync::Once //! [`RwLock`]: crate::sync::RwLock </ins> #![stable(feature = "rust1", since = "1.0.0")]

Discussion:
Part of Here's what needs to be done to close out this issue: is very small. It should explain what the module is for in more detail, with some examples. could use links to the types it references. has very... dry docs that aren't very helpful. And there's no examples. (link is just to BOOL but all of them) could use examples. (link is to Bool but all of them) are mostly fine, but could use links to other types and some beefing up generally. needs a bunch of types linked. should explain its relationship with and link to it. needs examples on its methods. needs to link to . needs examples. needs examples, links to types, and a comparison between it and . should link to the method that creates it. needs to link to the function that creates it. needs a link to and some examples. needs links. needs links. could do a much better job of explaining itself. needs a lot of links. The docs are good but a bit jargon-heavy, expanding those would be nice. needs more links and to explain how you get one. is the same. needs links, examples, and more explanation of what it is. needs to link to . needs links. has the same issues as . has the same as . needs to link to how to create one. needs to link to . needs to link to needs to link to . has almost no docs and it's the focus of this module! should point to and then tell how it's different.
Possible inconsistency in the Rust documentation about channels: Function std::sync::mpsc::syncchannel "As with asynchronous channels, all senders will panic in send if the Receiver has been destroyed" Struct std::sync::mpsc::SyncSender: fn send(&self, t: T) -Result<(), SendError<T"This function will never panic, but it may return Err if the Receiver has disconnected and is no longer able to receive information."
I'm working on updating the docs to more closely match the refined docs from .
I am happy to mentor anyone who wants to tackle this issue.
for all the ones that need links, are you talking about for example the types wrapped in tags, such as under the page?

Is it safe to say that as general rule every type under a tag should link to the page for that type? Is there other linking on these pages you would expect to see?
Yes, exactly. Note that sometimes there is a bug here; that is, certain kinds of docs get rendered on two pages and so the links won't work. I don't think that's an issue here, but our tools will catch those cases, so you shouldn't worry about it too much, but figured it'd be worth a mention. That's pretty much it, just the stuff that's in already.
Someone looks to have fixed up on nightly, btw.
Ah, I made these off of the stable links, I think :(
can we check some boxes off to track progress and make it easier to see where we're at? Things that I believe can be marked off: -merged, but I could understand if you want more stuff here -merged -merged -looks good to me on nightly -has links on nightly -has links on nightly Awaiting merge/approval: -going to be merged, could as well be marked off I think -looks good, too, but waiting for approval
done, thank you!
Condvar has examples on its methods, but the ones for wait* seem to contain race conditions. WaitTimeoutResult::timedout has an example that does not use the method (it is copied from the incorrect example for Condvar::wait_timeout).
I think worked on the Condvar examples?
It's very possible, I had issue with timeout stuff...
is the list of things to do in this module up to date ? I was thinking on tackling this module once I am done with the module (probably on Monday). If no one else is working on this I'll try to document the whole module for the next week (and maybe a little bit of the next one).
More or less. It still has a lot of places to improvement anyway so feel free to give it a try!
so everything starting with Weak and going down should be done now, it's just not marked off. I've been working on rewriting this page: : , but that relates more to this issue: , and I have been distracted so it's going slow. I hope to get it done this week. Atomic fence may be done, also, I've seen some PR's for it. But would need to clarify.

So everything else should be up for grabs and of course nothing's stopping you from improving any given page further.
I completed the subtask with
ditto for and . What did you have in mind for changes to ?
thank you! So I'm looking at them now, and they're pretty good. Mostly, there's a few types mentioned that don't have links, like how doesn't have a link to I wonder if we should point to the module documentation as well, like, add a sentence to each type saying Thoughts?