nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2024-11-23 07:14:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

aliasing guarantee

Browse Source
This commit is contained in:
Manish Goregaokar 2023-07-26 18:41:37 -07:00
parent 778fdf2dfb
commit 3809c091fc
1 changed files with 40 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
library/alloc/src/vec/mod.rs
View File

@ -1218,11 +1218,14 @@ impl<T, A: Allocator> Vec<T, A> {
/// is never written to (except inside an `UnsafeCell`) using this pointer or any pointer
/// derived from it. If you need to mutate the contents of the slice, use [`as_mut_ptr`].
///
/// This method guarantees that when it is called multiple times without
/// the buffer being reallocated in the mean time, the returned pointer will
/// always be exactly the same, even for the purpose of the aliasing model, where
/// pointers may be invalidated even when the actual memory does not move.
/// See the second example below for how this can be used.
/// This method guarantees that for the purpose of the aliasing model, this method
/// does not materialize a reference to the underlying slice, and thus the returned pointer
/// will remain valid when mixed with other calls to [`as_ptr`] and [`as_mut_ptr`],
/// Note that calling other methods that materialize mutable references to the slice,
/// or references to specific elements you are planning on accessing through this pointer,
/// may still invalidate this pointer.
/// See the second example below for how this guarantee can be used.
///
///
/// # Examples
///
@ -1237,17 +1240,22 @@ impl<T, A: Allocator> Vec<T, A> {
/// }
/// ```
///
/// The validity guarantee works out this way:
/// Due to the aliasing guarantee, the following code is legal:
///
/// ```rust
/// let mut v = vec![0];
/// let ptr = v.as_ptr();
/// let x = ptr.read();
/// v[0] = 5;
/// // Notably, the write above did *not* invalidate `ptr1`:
/// let x = ptr.read();
/// unsafe {
/// let mut v = vec![0];
/// let ptr1 = v.as_ptr();
/// let _ = ptr1.read();
/// let ptr2 = v.as_mut_ptr();
/// ptr2.write(2);
/// // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
/// let _ = ptr1.read();
/// }
/// ```
///
/// [`as_mut_ptr`]: Vec::as_mut_ptr
/// [`as_ptr`]: Vec::as_ptr
#[stable(feature = "vec_as_ptr", since = "1.37.0")]
#[inline]
pub fn as_ptr(&self) -> *const T {
@ -1264,11 +1272,13 @@ impl<T, A: Allocator> Vec<T, A> {
/// Modifying the vector may cause its buffer to be reallocated,
/// which would also make any pointers to it invalid.
///
/// This method guarantees that when it is called multiple times without
/// the buffer being reallocated in the mean time, the returned pointer will
/// always be exactly the same, even for the purpose of the aliasing model, where
/// pointers may be invalidated even when the actual memory does not move.
/// See the second example below for how this can be used.
/// This method guarantees that for the purpose of the aliasing model, this method
/// does not materialize a reference to the underlying slice, and thus the returned pointer
/// will remain valid when mixed with other calls to [`as_ptr`] and [`as_mut_ptr`],
/// Note that calling other methods that materialize references to the slice,
/// or references to specific elements you are planning on accessing through this pointer,
/// may still invalidate this pointer.
/// See the second example below for how this guarantee can be used.
///
///
/// # Examples
@ -1289,17 +1299,22 @@ impl<T, A: Allocator> Vec<T, A> {
/// assert_eq!(&*x, &[0, 1, 2, 3]);
/// ```
///
/// The validity guarantee works out this way:
/// Due to the aliasing guarantee, the following code is legal:
///
/// ```rust
/// let mut v = vec![0];
/// let ptr1 = v.as_mut_ptr();
/// ptr1.write(1);
/// let ptr2 = v.as_mut_ptr();
/// ptr2.write(2);
/// // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
/// ptr1.write(3);
/// unsafe {
/// let mut v = vec![0];
/// let ptr1 = v.as_mut_ptr();
/// ptr1.write(1);
/// let ptr2 = v.as_mut_ptr();
/// ptr2.write(2);
/// // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
/// ptr1.write(3);
/// }
/// ```
///
/// [`as_mut_ptr`]: Vec::as_mut_ptr
/// [`as_ptr`]: Vec::as_ptr
#[stable(feature = "vec_as_ptr", since = "1.37.0")]
#[inline]
pub fn as_mut_ptr(&mut self) -> *mut T {