From b372dce3bf3af99f046329f2d24f6d7b107c6d11 Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Sat, 18 Jul 2026 10:33:34 +0200 Subject: [PATCH 1/2] allocations: document that they can be read-only --- library/core/src/ptr/mod.rs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/library/core/src/ptr/mod.rs b/library/core/src/ptr/mod.rs index c758d5f4b89d6..5a54eb8643289 100644 --- a/library/core/src/ptr/mod.rs +++ b/library/core/src/ptr/mod.rs @@ -119,11 +119,20 @@ //! fully contiguous (i.e., has no "holes"), there is no guarantee that this //! will not change in the future. //! +//! An allocation can be either mutable (the common case) or *read-only*. +//! Read-only allocations are implicitly introduced by the compiler for `static` items without +//! interior mutability and for `const` items. Writing or creating a mutable reference to a +//! read-only allocation is undefined behavior, and most atomic operations are not supported +//! for read-only allocations either (see [here][atomic-ro] for exceptions). +//! +//! [atomic-ro]: crate::sync::atomic#atomic-accesses-to-read-only-memory +//! //! Allocations must behave like "normal" memory: in particular, reads must not have //! side-effects, and writes must become visible to other threads using the usual synchronization //! primitives. //! Allocations must support all atomic operations that are available for the target (as //! determined by the `target_has_atomic*` set of cfg flags). +//! Read-only allocations only have to support the operations [permitted there][atomic-ro]. //! The precise instructions used for atomic operations are generally not guaranteed, so portable //! software should place all Rust allocations in memory regions that support all atomic //! instructions. From 2a8cada0b313cd9f0f6ba3dcc5e0879f52116ea9 Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Wed, 22 Jul 2026 21:21:47 +0200 Subject: [PATCH 2/2] mention target-specific limitations can exist Co-authored-by: Jacob Lifshay --- library/core/src/ptr/mod.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/library/core/src/ptr/mod.rs b/library/core/src/ptr/mod.rs index 5a54eb8643289..1b393e6c928e8 100644 --- a/library/core/src/ptr/mod.rs +++ b/library/core/src/ptr/mod.rs @@ -124,8 +124,11 @@ //! interior mutability and for `const` items. Writing or creating a mutable reference to a //! read-only allocation is undefined behavior, and most atomic operations are not supported //! for read-only allocations either (see [here][atomic-ro] for exceptions). +//! Additionally, some target-specific intrinsics are not supported on read-only +//! allocations even if their memory write is masked off, such as [`_mm_maskmoveu_si128`]. //! //! [atomic-ro]: crate::sync::atomic#atomic-accesses-to-read-only-memory +//! [`_mm_maskmoveu_si128`]: ../../core/arch/x86/fn._mm_maskmoveu_si128.html //! //! Allocations must behave like "normal" memory: in particular, reads must not have //! side-effects, and writes must become visible to other threads using the usual synchronization