From 5443182f28a17988bffcd929b9954ebb6475bf81 Mon Sep 17 00:00:00 2001 From: Vitali Borsak Date: Mon, 8 Sep 2025 16:20:17 +0000 Subject: [PATCH 01/15] Rebasing and adding initial commit of the Concurrency Chapter --- src/concurrency.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 src/concurrency.md diff --git a/src/concurrency.md b/src/concurrency.md new file mode 100644 index 00000000..f7084cd7 --- /dev/null +++ b/src/concurrency.md @@ -0,0 +1,7 @@ +r[concurrency] +# Concurrency + +r[concurrency.intro] +Rust provides language and library features for writing concurrent programs. These features are designed to prevent data races --- situations in which multiple threads access the same memory without proper synchronization, with at least one of the accesses modifying that memory. + +This chapter describes the traits, types, and concepts that Rust uses to express and enforce safe concurrency. From f200b191cc0aa9eefefcb69b8a46ea89b9408831 Mon Sep 17 00:00:00 2001 From: Vitali Borsak Date: Fri, 10 Oct 2025 10:13:46 +0100 Subject: [PATCH 02/15] Adding concurrent program definition to the glossary and referencing it in the concurrency chapter --- src/concurrency.md | 4 +++- src/glossary.md | 4 ++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/src/concurrency.md b/src/concurrency.md index f7084cd7..ebd89264 100644 --- a/src/concurrency.md +++ b/src/concurrency.md @@ -2,6 +2,8 @@ r[concurrency] # Concurrency r[concurrency.intro] -Rust provides language and library features for writing concurrent programs. These features are designed to prevent data races --- situations in which multiple threads access the same memory without proper synchronization, with at least one of the accesses modifying that memory. +Rust provides language and library features for writing [concurrent programs]. These features are designed to prevent data races --- situations in which multiple threads access the same memory without proper synchronization, with at least one of the accesses modifying that memory. This chapter describes the traits, types, and concepts that Rust uses to express and enforce safe concurrency. + +[concurrent programs]: glossary.md#concurrent-program diff --git a/src/glossary.md b/src/glossary.md index fa5edee2..84c28e1c 100644 --- a/src/glossary.md +++ b/src/glossary.md @@ -50,6 +50,10 @@ Combinators are higher-order functions that apply only functions and earlier defined combinators to provide a result from its arguments. They can be used to manage control flow in a modular fashion. +### Concurrent program + +A concurrent program is a program that can perform multiple tasks or processes at the same time, possibly overlapping in execution. + ### Crate A crate is the unit of compilation and linking. There are different [types of From ce37fa27ce8023bc80428cfeebcce2db2371bb23 Mon Sep 17 00:00:00 2001 From: Vitali Borsak Date: Fri, 10 Oct 2025 10:30:20 +0100 Subject: [PATCH 03/15] Adding data race definition to the glossary and referencing it in the concurrency chapter --- src/concurrency.md | 3 ++- src/glossary.md | 4 ++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/src/concurrency.md b/src/concurrency.md index ebd89264..e796e9cb 100644 --- a/src/concurrency.md +++ b/src/concurrency.md @@ -2,8 +2,9 @@ r[concurrency] # Concurrency r[concurrency.intro] -Rust provides language and library features for writing [concurrent programs]. These features are designed to prevent data races --- situations in which multiple threads access the same memory without proper synchronization, with at least one of the accesses modifying that memory. +Rust provides language and library features for writing [concurrent programs]. These features are designed to prevent [data races] --- situations in which multiple threads access the same memory without proper synchronization, with at least one of the accesses modifying that memory. This chapter describes the traits, types, and concepts that Rust uses to express and enforce safe concurrency. [concurrent programs]: glossary.md#concurrent-program +[data races]: glossary.md#data-race diff --git a/src/glossary.md b/src/glossary.md index 84c28e1c..89a9215f 100644 --- a/src/glossary.md +++ b/src/glossary.md @@ -64,6 +64,10 @@ may be made visible to other crates by marking them as public in the crate root, including through [paths] of public modules. [More][crate]. +### Data race + +A data race occurs when multiple threads attempt to access the same shared memory location concurrently. + ### Dispatch Dispatch is the mechanism to determine which specific version of code is actually run when it involves polymorphism. Two major forms of dispatch are static dispatch and dynamic dispatch. Rust supports dynamic dispatch through the use of [trait objects][type.trait-object]. From db28b94aac2f6b93aa311fbe36761124b26f87fc Mon Sep 17 00:00:00 2001 From: Vitali Borsak Date: Fri, 10 Oct 2025 16:13:31 +0100 Subject: [PATCH 04/15] Adding Concurrency chapter to the summary --- src/SUMMARY.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index cbee8c01..a4073433 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -131,6 +131,8 @@ - [The Rust runtime](runtime.md) +- [Concurrency](concurrency.md) + - [Appendices](appendices.md) - [Grammar summary](grammar.md) - [Macro Follow-Set Ambiguity Formal Specification](macro-ambiguity.md) From a19bc1e763b98dd3b1a215f05cc6b934edca8c2e Mon Sep 17 00:00:00 2001 From: Vitali Borsak Date: Wed, 29 Oct 2025 15:43:10 +0000 Subject: [PATCH 05/15] Adding Send and Sync section along with the intro to this section --- src/concurrency.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/concurrency.md b/src/concurrency.md index e796e9cb..e33d1486 100644 --- a/src/concurrency.md +++ b/src/concurrency.md @@ -6,5 +6,17 @@ Rust provides language and library features for writing [concurrent programs]. T This chapter describes the traits, types, and concepts that Rust uses to express and enforce safe concurrency. +r[concurrency.send-and-sync] +## Send and Sync + +r[concurrency.send-and-sync.intro] +The [`Send`] and [`Sync`] traits are [unsafe traits] used by the Rust type system to track which types can be safely used across thread boundaries. + +These traits are marker traits with no methods. Implementing them asserts that a type has the intrinsic properties required for safe concurrent use. The compiler automatically implements these traits for most types when possible, but they can also be implemented manually. Providing an incorrect manual implementation can cause [undefined behavior]. + [concurrent programs]: glossary.md#concurrent-program [data races]: glossary.md#data-race +[`Send`]: special-types-and-traits.md#Send +[`Sync`]: special-types-and-traits.md#Sync +[unsafe traits]: items/traits.md#unsafe-traits +[undefined behavior]: glossary.md#undefined_behavior From fc4a6201fecfe7fc67d907244c8e5a4068ebeb3f Mon Sep 17 00:00:00 2001 From: Vitali Borsak Date: Wed, 29 Oct 2025 15:46:03 +0000 Subject: [PATCH 06/15] Adding marker trait definition to the glossary --- src/concurrency.md | 5 +++-- src/glossary.md | 6 ++++++ 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/src/concurrency.md b/src/concurrency.md index e33d1486..a1422984 100644 --- a/src/concurrency.md +++ b/src/concurrency.md @@ -12,11 +12,12 @@ r[concurrency.send-and-sync] r[concurrency.send-and-sync.intro] The [`Send`] and [`Sync`] traits are [unsafe traits] used by the Rust type system to track which types can be safely used across thread boundaries. -These traits are marker traits with no methods. Implementing them asserts that a type has the intrinsic properties required for safe concurrent use. The compiler automatically implements these traits for most types when possible, but they can also be implemented manually. Providing an incorrect manual implementation can cause [undefined behavior]. +These traits are [marker traits] with no methods. Implementing them asserts that a type has the intrinsic properties required for safe concurrent use. The compiler automatically implements these traits for most types when possible, but they can also be implemented manually. Providing an incorrect manual implementation can cause [undefined behavior]. [concurrent programs]: glossary.md#concurrent-program [data races]: glossary.md#data-race [`Send`]: special-types-and-traits.md#Send [`Sync`]: special-types-and-traits.md#Sync [unsafe traits]: items/traits.md#unsafe-traits -[undefined behavior]: glossary.md#undefined_behavior +[marker traits]: glossary.md#marker-trait +[undefined behavior]: glossary.md#undefined-behavior diff --git a/src/glossary.md b/src/glossary.md index 89a9215f..4a93477f 100644 --- a/src/glossary.md +++ b/src/glossary.md @@ -145,6 +145,12 @@ This is not affected by applied type arguments. `struct Foo` is considered local `Vec` is not. `LocalType` is local. Type aliases do not affect locality. +### Marker trait +A trait that has no associated items (no methods, no associated types, and no constants) +and is used only to mark that a type has a particular property. +Implementing a marker trait does not change a type’s behavior at runtime; +it simply communicates to the compiler and to other code that the type satisfies some condition. + ### Module A module is a container for zero or more [items]. Modules are organized in a From 28331948e2b60468f7a88e25fa33bf575cff5a86 Mon Sep 17 00:00:00 2001 From: Vitali Borsak Date: Thu, 30 Oct 2025 10:34:39 +0000 Subject: [PATCH 07/15] Altering the Send and Sync section intro and adding some code examples --- src/concurrency.md | 53 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 51 insertions(+), 2 deletions(-) diff --git a/src/concurrency.md b/src/concurrency.md index a1422984..07e139a1 100644 --- a/src/concurrency.md +++ b/src/concurrency.md @@ -12,7 +12,57 @@ r[concurrency.send-and-sync] r[concurrency.send-and-sync.intro] The [`Send`] and [`Sync`] traits are [unsafe traits] used by the Rust type system to track which types can be safely used across thread boundaries. -These traits are [marker traits] with no methods. Implementing them asserts that a type has the intrinsic properties required for safe concurrent use. The compiler automatically implements these traits for most types when possible, but they can also be implemented manually. Providing an incorrect manual implementation can cause [undefined behavior]. +These traits are [marker traits] with no methods. Implementing them (whether manually or via the compiler's automatic implementation) asserts that a type has the intrinsic properties required for safe concurrent use. + +Library functions that require types that can be sent across threads require [`Send`]. +```rust +// This will compile successfully +// A type is `Send` if it can be safely transferred to another thread. +fn assert_send() {} + +fn main() { + assert_send::(); // primitive types are Send + assert_send::>(); // Vec is Send if T is Send +} +``` + +```rust,compile_fail +// This will not compile +// A type containing `Rc` is not `Send`. +use std::rc::Rc; + +fn assert_send() {} + +fn main() { + let _x = Rc::new(1); + assert_send::>(); //~ error[E0277] `Rc` cannot be sent between threads safely +} +``` + +Library functions that require types that can be accessed concurrently from multiple threads require [`Sync`]. +```rust +// This will compile successfully +// A type is `Sync` if it can be safely referenced from multiple threads. +fn assert_sync() {} + +fn main() { + assert_sync::(); // i32 is Sync + assert_sync::<&'static str>(); // string slices are Sync + assert_sync::>(); // Arc is Sync if T is Sync +} +``` + +```rust,compile_fail +// This will not compile +// A type containing `Cell` is not `Sync`. +use std::cell::Cell; + +fn assert_sync() {} + +fn main() { + assert_sync::>(); //~ error[E0277] `*const i32` cannot be shared between threads safely +} +``` [concurrent programs]: glossary.md#concurrent-program [data races]: glossary.md#data-race @@ -20,4 +70,3 @@ These traits are [marker traits] with no methods. Implementing them asserts that [`Sync`]: special-types-and-traits.md#Sync [unsafe traits]: items/traits.md#unsafe-traits [marker traits]: glossary.md#marker-trait -[undefined behavior]: glossary.md#undefined-behavior From 01be8a0d7f66935add5948175c8be22bd3bade0e Mon Sep 17 00:00:00 2001 From: Vitali Borsak Date: Thu, 30 Oct 2025 20:20:07 +0000 Subject: [PATCH 08/15] Attempting to fix linking issue --- src/concurrency.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/concurrency.md b/src/concurrency.md index 07e139a1..124f6f1b 100644 --- a/src/concurrency.md +++ b/src/concurrency.md @@ -66,7 +66,7 @@ fn main() { [concurrent programs]: glossary.md#concurrent-program [data races]: glossary.md#data-race -[`Send`]: special-types-and-traits.md#Send -[`Sync`]: special-types-and-traits.md#Sync +[`Send`]: special-types-and-traits.md#send +[`Sync`]: special-types-and-traits.md#sync [unsafe traits]: items/traits.md#unsafe-traits [marker traits]: glossary.md#marker-trait From 26be81d1ba2988e6d40b87bf931ece197a7f26d4 Mon Sep 17 00:00:00 2001 From: Vitali Borsak Date: Mon, 3 Nov 2025 16:12:22 +0000 Subject: [PATCH 09/15] Updating a test and adding some additional corss-references --- src/concurrency.md | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/src/concurrency.md b/src/concurrency.md index 124f6f1b..727cc432 100644 --- a/src/concurrency.md +++ b/src/concurrency.md @@ -10,7 +10,7 @@ r[concurrency.send-and-sync] ## Send and Sync r[concurrency.send-and-sync.intro] -The [`Send`] and [`Sync`] traits are [unsafe traits] used by the Rust type system to track which types can be safely used across thread boundaries. +The [`Send`] and [`Sync`] [auto traits] are [unsafe traits] used by the Rust type system to track which types can be safely used across thread boundaries. These traits are [marker traits] with no methods. Implementing them (whether manually or via the compiler's automatic implementation) asserts that a type has the intrinsic properties required for safe concurrent use. @@ -26,16 +26,29 @@ fn main() { } ``` +Something that awaits something that isn't sync will produce a [`core::future::Future`] that is not [`Send`]. ```rust,compile_fail // This will not compile // A type containing `Rc` is not `Send`. use std::rc::Rc; -fn assert_send() {} +// This async function awaits something that uses an Rc (which is !Send) +async fn not_send_future() { + let rc = Rc::new(42); + + // Simulate an async operation that captures `rc` + let _ = async { + println!("{}", rc); + }.await; +} + +// A helper function that requires its argument to be Send +fn assert_send(_: T) {} fn main() { - let _x = Rc::new(1); - assert_send::>(); //~ error[E0277] `Rc` cannot be sent between threads safely + let fut = not_send_future(); + + assert_send(fut); //~ error[E0277] `*const i32` cannot be shared between threads safely } ``` @@ -68,5 +81,7 @@ fn main() { [data races]: glossary.md#data-race [`Send`]: special-types-and-traits.md#send [`Sync`]: special-types-and-traits.md#sync +[auto traits]: special-types-and-traits.md#auto-traits [unsafe traits]: items/traits.md#unsafe-traits [marker traits]: glossary.md#marker-trait +[`core::future::Future`]: https://doc.rust-lang.org/stable/core/future/trait.Future.html From 5266fb9f1ca953e2b2078b424c09eb661a47db12 Mon Sep 17 00:00:00 2001 From: Vitali Borsak Date: Tue, 4 Nov 2025 10:53:07 +0000 Subject: [PATCH 10/15] Adding a new Atomics section along with an intro and a test --- src/concurrency.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/src/concurrency.md b/src/concurrency.md index 727cc432..2f553a47 100644 --- a/src/concurrency.md +++ b/src/concurrency.md @@ -77,6 +77,35 @@ fn main() { } ``` +r[concurrency.atomics] +## Atomics + +r[concurrency.atomics.intro] +Atomic types allow multiple threads to safely read and write shared values without using explicit locks by providing atomic operations such as atomic loads, stores, and read-modify-write with configurable memory ordering. + +```rust +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::thread; + +fn main() { + static COUNTER: AtomicUsize = AtomicUsize::new(0); + + let handles: Vec<_> = (0..10) + .map(|_| { + thread::spawn(|| { + for _ in 0..1000 { + COUNTER.fetch_add(1, Ordering::Relaxed); + } + }) + }) + .collect(); + + for handle in handles { + handle.join().unwrap(); + } +} +``` + [concurrent programs]: glossary.md#concurrent-program [data races]: glossary.md#data-race [`Send`]: special-types-and-traits.md#send From 74fb0694400aed0d2c06464138bce95782748759 Mon Sep 17 00:00:00 2001 From: Vitali Borsak Date: Tue, 4 Nov 2025 10:56:17 +0000 Subject: [PATCH 11/15] Adding atomic type definition to the glossary --- src/concurrency.md | 3 ++- src/glossary.md | 4 ++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/src/concurrency.md b/src/concurrency.md index 2f553a47..8c23577d 100644 --- a/src/concurrency.md +++ b/src/concurrency.md @@ -81,7 +81,7 @@ r[concurrency.atomics] ## Atomics r[concurrency.atomics.intro] -Atomic types allow multiple threads to safely read and write shared values without using explicit locks by providing atomic operations such as atomic loads, stores, and read-modify-write with configurable memory ordering. +[Atomic types] allow multiple threads to safely read and write shared values without using explicit locks by providing atomic operations such as atomic loads, stores, and read-modify-write with configurable memory ordering. ```rust use std::sync::atomic::{AtomicUsize, Ordering}; @@ -114,3 +114,4 @@ fn main() { [unsafe traits]: items/traits.md#unsafe-traits [marker traits]: glossary.md#marker-trait [`core::future::Future`]: https://doc.rust-lang.org/stable/core/future/trait.Future.html +[Atomic types]: glossary.md#atomic-types diff --git a/src/glossary.md b/src/glossary.md index 4a93477f..be9b8fc3 100644 --- a/src/glossary.md +++ b/src/glossary.md @@ -30,6 +30,10 @@ items are defined in [implementations] and declared in [traits]. Only functions, constants, and type aliases can be associated. Contrast to a [free item]. +### Atomic types + +Atomic types provide primitive shared-memory communication between threads, and are the building blocks of other concurrent types. + ### Blanket implementation Any implementation where a type appears [uncovered](#uncovered-type). `impl Foo From daed96bc97b2e7dbe12d276563c213efabe46c3f Mon Sep 17 00:00:00 2001 From: Vitali Borsak Date: Tue, 4 Nov 2025 11:15:51 +0000 Subject: [PATCH 12/15] Adding atomics thread safety paragraph with an example --- src/concurrency.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/src/concurrency.md b/src/concurrency.md index 8c23577d..719995b3 100644 --- a/src/concurrency.md +++ b/src/concurrency.md @@ -106,6 +106,27 @@ fn main() { } ``` +r[concurrency.atomics.thread-safety] +Atomic operations are guaranteed to be indivisible: no other thread can observe a value half-written or perform a conflicting update in the middle of an atomic operation. Correct use of atomic types can prevent [data races], but misuse may still cause higher-level concurrency bugs such as deadlocks or livelocks. + +```rust +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::thread; + +fn main() { + static VALUE: AtomicUsize = AtomicUsize::new(0); + + let t1 = thread::spawn(|| VALUE.store(1, Ordering::Relaxed)); + let t2 = thread::spawn(|| VALUE.store(2, Ordering::Relaxed)); + + t1.join().unwrap(); + t2.join().unwrap(); + + // VALUE is guaranteed to be either 1 or 2 — never a corrupted mix. + println!("{}", VALUE.load(Ordering::Relaxed)); +} +``` + [concurrent programs]: glossary.md#concurrent-program [data races]: glossary.md#data-race [`Send`]: special-types-and-traits.md#send From 851e745a1cafa33eed827af51cc8d19d7a88ee12 Mon Sep 17 00:00:00 2001 From: Vitali Borsak Date: Tue, 4 Nov 2025 11:22:13 +0000 Subject: [PATCH 13/15] Adding atomics mapping paragraph --- src/concurrency.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/src/concurrency.md b/src/concurrency.md index 719995b3..7f7cea72 100644 --- a/src/concurrency.md +++ b/src/concurrency.md @@ -127,6 +127,24 @@ fn main() { } ``` +r[concurrency.atomics.mapping] +The following table lists the atomic types and the corresponding primitive types they represent: + +| Primitive Type | Atomic Type | +| -------------- | ------------------------------------- | +| `bool` | [`core::sync::atomic::AtomicBool`] | +| `i8` | [`core::sync::atomic::AtomicI8`] | +| `i16` | [`core::sync::atomic::AtomicI16`] | +| `i32` | [`core::sync::atomic::AtomicI32`] | +| `i64` | [`core::sync::atomic::AtomicI64`] | +| `isize` | [`core::sync::atomic::AtomicIsize`] | +| `u8` | [`core::sync::atomic::AtomicU8`] | +| `u16` | [`core::sync::atomic::AtomicU16`] | +| `u32` | [`core::sync::atomic::AtomicU32`] | +| `u64` | [`core::sync::atomic::AtomicU64`] | +| `usize` | [`core::sync::atomic::AtomicUsize`] | +| `*mut T` | [`core::sync::atomic::AtomicPtr`] | + [concurrent programs]: glossary.md#concurrent-program [data races]: glossary.md#data-race [`Send`]: special-types-and-traits.md#send @@ -136,3 +154,15 @@ fn main() { [marker traits]: glossary.md#marker-trait [`core::future::Future`]: https://doc.rust-lang.org/stable/core/future/trait.Future.html [Atomic types]: glossary.md#atomic-types +[`core::sync::atomic::AtomicBool`]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicBool.html +[`core::sync::atomic::AtomicI8`]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicI8.html +[`core::sync::atomic::AtomicI16`]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicI16.html +[`core::sync::atomic::AtomicI32`]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicI32.html +[`core::sync::atomic::AtomicI64`]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicI64.html +[`core::sync::atomic::AtomicIsize`]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicIsize.html +[`core::sync::atomic::AtomicU8`]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicU8.html +[`core::sync::atomic::AtomicU16`]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicU16.html +[`core::sync::atomic::AtomicU32`]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicU32.html +[`core::sync::atomic::AtomicU64`]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicU64.html +[`core::sync::atomic::AtomicUsize`]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicUsize.html +[`core::sync::atomic::AtomicPtr`]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicPtr.html From 128605fb8fe09f17e4a0fd8bee5bbb0a03289208 Mon Sep 17 00:00:00 2001 From: Vitali Borsak Date: Wed, 5 Nov 2025 09:56:15 +0000 Subject: [PATCH 14/15] Adding atomics usage sentence with an example test --- src/concurrency.md | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/src/concurrency.md b/src/concurrency.md index 7f7cea72..c1ec114e 100644 --- a/src/concurrency.md +++ b/src/concurrency.md @@ -107,7 +107,7 @@ fn main() { ``` r[concurrency.atomics.thread-safety] -Atomic operations are guaranteed to be indivisible: no other thread can observe a value half-written or perform a conflicting update in the middle of an atomic operation. Correct use of atomic types can prevent [data races], but misuse may still cause higher-level concurrency bugs such as deadlocks or livelocks. +Atomic operations are guaranteed to be indivisible: no other thread can observe a value half-written or perform a conflicting update in the middle of an atomic operation. Correct use of atomic types can prevent [data races], but misuse may still cause higher-level concurrency bugs such as deadlocks or livelocks. ```rust use std::sync::atomic::{AtomicUsize, Ordering}; @@ -122,7 +122,7 @@ fn main() { t1.join().unwrap(); t2.join().unwrap(); - // VALUE is guaranteed to be either 1 or 2 — never a corrupted mix. + // VALUE is guaranteed to be either 1 or 2, never a corrupted mix. println!("{}", VALUE.load(Ordering::Relaxed)); } ``` @@ -145,6 +145,33 @@ The following table lists the atomic types and the corresponding primitive types | `usize` | [`core::sync::atomic::AtomicUsize`] | | `*mut T` | [`core::sync::atomic::AtomicPtr`] | +r[concurrency.atomics.usage] +Atomic types are [`Sync`], meaning references to them can be safely shared between threads. Using atomic operations correctly may require careful reasoning about memory ordering. + +```rust +use std::sync::atomic::{ + AtomicBool, AtomicI8, AtomicI16, AtomicI32, AtomicI64, + AtomicIsize, AtomicU8, AtomicU16, AtomicU32, AtomicU64, + AtomicUsize, +}; + +fn assert_sync() {} + +fn main() { + assert_sync::(); + assert_sync::(); + assert_sync::(); + assert_sync::(); + assert_sync::(); + assert_sync::(); + assert_sync::(); + assert_sync::(); + assert_sync::(); + assert_sync::(); + assert_sync::(); +} +``` + [concurrent programs]: glossary.md#concurrent-program [data races]: glossary.md#data-race [`Send`]: special-types-and-traits.md#send From dfbdc681d1eb1a534efa5e2e588060d553f08609 Mon Sep 17 00:00:00 2001 From: Vitali Borsak Date: Wed, 5 Nov 2025 10:54:08 +0000 Subject: [PATCH 15/15] Adding cross-reference to the memory model. --- src/concurrency.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/concurrency.md b/src/concurrency.md index c1ec114e..35d7fc8b 100644 --- a/src/concurrency.md +++ b/src/concurrency.md @@ -106,6 +106,8 @@ fn main() { } ``` +The semantics of these operations are defined by Rust’s [memory model]. + r[concurrency.atomics.thread-safety] Atomic operations are guaranteed to be indivisible: no other thread can observe a value half-written or perform a conflicting update in the middle of an atomic operation. Correct use of atomic types can prevent [data races], but misuse may still cause higher-level concurrency bugs such as deadlocks or livelocks. @@ -181,6 +183,7 @@ fn main() { [marker traits]: glossary.md#marker-trait [`core::future::Future`]: https://doc.rust-lang.org/stable/core/future/trait.Future.html [Atomic types]: glossary.md#atomic-types +[memory model]: memory-model.md#memory-model [`core::sync::atomic::AtomicBool`]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicBool.html [`core::sync::atomic::AtomicI8`]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicI8.html [`core::sync::atomic::AtomicI16`]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicI16.html