From 05ffd446a9b2d2c67c450bea4180eb4790939e07 Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Thu, 29 Aug 2024 16:06:20 +0200 Subject: [PATCH 1/2] Box validity: update for new zero-sized rules --- library/alloc/src/boxed.rs | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/library/alloc/src/boxed.rs b/library/alloc/src/boxed.rs index 38b1766c17440..b3a3cf1bbeaaa 100644 --- a/library/alloc/src/boxed.rs +++ b/library/alloc/src/boxed.rs @@ -53,22 +53,19 @@ //! //! # Memory layout //! -//! For non-zero-sized values, a [`Box`] will use the [`Global`] allocator for -//! its allocation. It is valid to convert both ways between a [`Box`] and a -//! raw pointer allocated with the [`Global`] allocator, given that the -//! [`Layout`] used with the allocator is correct for the type. More precisely, -//! a `value: *mut T` that has been allocated with the [`Global`] allocator -//! with `Layout::for_value(&*value)` may be converted into a box using -//! [`Box::::from_raw(value)`]. Conversely, the memory backing a `value: *mut -//! T` obtained from [`Box::::into_raw`] may be deallocated using the -//! [`Global`] allocator with [`Layout::for_value(&*value)`]. +//! For non-zero-sized values, a [`Box`] will use the [`Global`] allocator for its allocation. It is +//! valid to convert both ways between a [`Box`] and a raw pointer allocated with the [`Global`] +//! allocator, given that the [`Layout`] used with the allocator is correct for the type and the raw +//! pointer points to a valid value of the right type. More precisely, a `value: *mut T` that has +//! been allocated with the [`Global`] allocator with `Layout::for_value(&*value)` may be converted +//! into a box using [`Box::::from_raw(value)`]. Conversely, the memory backing a `value: *mut T` +//! obtained from [`Box::::into_raw`] may be deallocated using the [`Global`] allocator with +//! [`Layout::for_value(&*value)`]. //! -//! For zero-sized values, the `Box` pointer still has to be [valid] for reads -//! and writes and sufficiently aligned. In particular, casting any aligned -//! non-zero integer literal to a raw pointer produces a valid pointer, but a -//! pointer pointing into previously allocated memory that since got freed is -//! not valid. The recommended way to build a Box to a ZST if `Box::new` cannot -//! be used is to use [`ptr::NonNull::dangling`]. +//! For zero-sized values, the `Box` pointer has to be non-null and sufficiently aligned. The +//! recommended way to build a Box to a ZST if `Box::new` cannot be used is to use +//! [`ptr::NonNull::dangling`]. Even for zero-sized types, the pointee type must be inhabited +//! to ensure that the Box points to a valid value of the given type. //! //! So long as `T: Sized`, a `Box` is guaranteed to be represented //! as a single pointer and is also ABI-compatible with C pointers From 0e5628d7de217454052d5246e994590fa7b75a93 Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Sun, 1 Sep 2024 11:21:37 +0200 Subject: [PATCH 2/2] tweak wording regarding Box validity --- library/alloc/src/boxed.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/library/alloc/src/boxed.rs b/library/alloc/src/boxed.rs index b3a3cf1bbeaaa..a924feaf15f2a 100644 --- a/library/alloc/src/boxed.rs +++ b/library/alloc/src/boxed.rs @@ -64,8 +64,9 @@ //! //! For zero-sized values, the `Box` pointer has to be non-null and sufficiently aligned. The //! recommended way to build a Box to a ZST if `Box::new` cannot be used is to use -//! [`ptr::NonNull::dangling`]. Even for zero-sized types, the pointee type must be inhabited -//! to ensure that the Box points to a valid value of the given type. +//! [`ptr::NonNull::dangling`]. +//! +//! On top of these basic layout requirements, a `Box` must point to a valid value of `T`. //! //! So long as `T: Sized`, a `Box` is guaranteed to be represented //! as a single pointer and is also ABI-compatible with C pointers