keos/sync/
mod.rs

1//! Synchronization primitives.
2//!
3//! Support similar synchronization primitives like `std::sync`.
4//!
5//! Belows sections is "copied" from `std::sync`'s documentation.
6//!
7//! ## The need for synchronization
8//!
9//! Conceptually, a Rust program is a series of operations which will
10//! be executed on a computer. The timeline of events happening in the
11//! program is consistent with the order of the operations in the code.
12//!
13//! Consider the following code, operating on some global static variables:
14//!
15//! ```rust
16//! static mut A: u32 = 0;
17//! static mut B: u32 = 0;
18//! static mut C: u32 = 0;
19//!
20//! fn main() {
21//!     unsafe {
22//!         A = 3;
23//!         B = 4;
24//!         A = A + B;
25//!         C = B;
26//!         println!("{A} {B} {C}");
27//!         C = A;
28//!     }
29//! }
30//! ```
31//!
32//! It appears as if some variables stored in memory are changed, an addition
33//! is performed, result is stored in `A` and the variable `C` is
34//! modified twice.
35//!
36//! When only a single thread is involved, the results are as expected:
37//! the line `7 4 4` gets printed.
38//!
39//! As for what happens behind the scenes, when optimizations are enabled the
40//! final generated machine code might look very different from the code:
41//!
42//! - The first store to `C` might be moved before the store to `A` or `B`, _as
43//!   if_ we had written `C = 4; A = 3; B = 4`.
44//!
45//! - Assignment of `A + B` to `A` might be removed, since the sum can be stored
46//!   in a temporary location until it gets printed, with the global variable
47//!   never getting updated.
48//!
49//! - The final result could be determined just by looking at the code at
50//!   compile time, so [constant folding] might turn the whole block into a
51//!   simple `println!("7 4 4")`.
52//!
53//! The compiler is allowed to perform any combination of these
54//! optimizations, as long as the final optimized code, when executed,
55//! produces the same results as the one without optimizations.
56//!
57//! Due to the [concurrency] involved in modern computers, assumptions
58//! about the program's execution order are often wrong. Access to
59//! global variables can lead to nondeterministic results, **even if**
60//! compiler optimizations are disabled, and it is **still possible**
61//! to introduce synchronization bugs.
62//!
63//! Note that thanks to Rust's safety guarantees, accessing global (static)
64//! variables requires `unsafe` code, assuming we don't use any of the
65//! synchronization primitives in this module.
66//!
67//! [constant folding]: https://en.wikipedia.org/wiki/Constant_folding
68//! [concurrency]: https://en.wikipedia.org/wiki/Concurrency_(computer_science)
69//!
70//! ## Higher-level synchronization objects
71//!
72//! Most of the low-level synchronization primitives are quite error-prone and
73//! inconvenient to use, which is why the standard library also exposes some
74//! higher-level synchronization objects.
75//!
76//! These abstractions can be built out of lower-level primitives.
77//! For efficiency, the sync objects in the standard library are usually
78//! implemented with help from the operating system's kernel, which is
79//! able to reschedule the threads while they are blocked on acquiring
80//! a lock.
81
82pub mod atomic;
83pub mod rwlock;
84pub mod spinlock;
85
86pub use rwlock::*;
87pub use spinlock::*;
keos/sync/mod.rs

keos/sync/
mod.rs
