diff --git a/src/libstd/sync/mod.rs b/src/libstd/sync/mod.rs index edbed430e38..d69ebc17622 100644 --- a/src/libstd/sync/mod.rs +++ b/src/libstd/sync/mod.rs @@ -12,11 +12,11 @@ //! //! ## The need for synchronization //! -//! Conceptually, a Rust program is simply 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. +//! 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. //! -//! Considering the following code, operating on some global static variables: +//! Consider the following code, operating on some global static variables: //! //! ```rust //! static mut A: u32 = 0; @@ -35,8 +35,10 @@ //! } //! ``` //! -//! 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. +//! 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. //! @@ -50,17 +52,19 @@ //! 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 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. +//! 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. +//! 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 @@ -74,7 +78,7 @@ //! Instructions can execute in a different order from the one we define, due to //! various reasons: //! -//! - **Compiler** reordering instructions: if the compiler can issue an +//! - 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. @@ -83,20 +87,20 @@ //! signal handlers or certain kinds of low-level code. //! Use [compiler fences] to prevent this reordering. //! -//! - **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. +//! - 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. //! -//! - **Multiprocessor** system, where multiple hardware threads run 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. +//! - 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 @@ -111,29 +115,49 @@ //! 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. +//! 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. //! -//! ## Efficiency +//! The following is an overview of the available synchronization +//! objects: //! -//! Higher-level synchronization mechanisms are usually heavy-weight. -//! While most atomic operations can execute instantaneously, acquiring a -//! [`Mutex`] can involve blocking until another thread releases it. -//! For [`RwLock`], while any number of readers may acquire it without -//! blocking, each writer will have exclusive access. +//! - [`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. //! -//! On the other hand, communication over [channels] can provide a fairly -//! high-level interface without sacrificing performance, at the cost of -//! somewhat more memory. +//! - [`Barrier`]: Ensures multiple threads will wait for each other +//! to reach a point in the program, before continuing execution all +//! together. //! -//! The more synchronization exists between CPUs, the smaller the performance -//! gains from multithreading will be. +//! - [`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 -//! [channels]: crate::sync::mpsc #![stable(feature = "rust1", since = "1.0.0")]