Something went wrong. Try again.
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587// SPDX-License-Identifier: (BSD-2-Clause OR Apache-2.0) OR MIT//// Copyright 2023 The Fuchsia Authors//// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.// This file may not be copied, modified, or distributed except according to// those terms.
#![allow(missing_docs)]
use core::{ fmt::{Debug, Formatter}, marker::PhantomData,};
use crate::{ pointer::{ inner::PtrInner, invariant::*, transmute::{MutationCompatible, SizeEq, TransmuteFromPtr}, }, AlignmentError, CastError, CastType, KnownLayout, SizeError, TryFromBytes, ValidityError,};
/// Module used to gate access to [`Ptr`]'s fields.mod def { #[cfg(doc)] use super::super::invariant; use super::*;
/// A raw pointer with more restrictions. /// /// `Ptr<T>` is similar to [`NonNull<T>`], but it is more restrictive in the /// following ways (note that these requirements only hold of non-zero-sized /// referents): /// - It must derive from a valid allocation. /// - It must reference a byte range which is contained inside the /// allocation from which it derives. /// - As a consequence, the byte range it references must have a size /// which does not overflow `isize`. /// /// Depending on how `Ptr` is parameterized, it may have additional /// invariants: /// - `ptr` conforms to the aliasing invariant of /// [`I::Aliasing`](invariant::Aliasing). /// - `ptr` conforms to the alignment invariant of /// [`I::Alignment`](invariant::Alignment). /// - `ptr` conforms to the validity invariant of /// [`I::Validity`](invariant::Validity). /// /// `Ptr<'a, T>` is [covariant] in `'a` and invariant in `T`. /// /// [`NonNull<T>`]: core::ptr::NonNull /// [covariant]: https://doc.rust-lang.org/reference/subtyping.html pub struct Ptr<'a, T, I> where T: ?Sized, I: Invariants, { /// # Invariants /// /// 0. `ptr` conforms to the aliasing invariant of /// [`I::Aliasing`](invariant::Aliasing). /// 1. `ptr` conforms to the alignment invariant of /// [`I::Alignment`](invariant::Alignment). /// 2. `ptr` conforms to the validity invariant of /// [`I::Validity`](invariant::Validity). // SAFETY: `PtrInner<'a, T>` is covariant in `'a` and invariant in `T`. ptr: PtrInner<'a, T>, _invariants: PhantomData<I>, }
impl<'a, T, I> Ptr<'a, T, I> where T: 'a + ?Sized, I: Invariants, { /// Constructs a new `Ptr` from a [`PtrInner`]. /// /// # Safety /// /// The caller promises that: /// /// 0. `ptr` conforms to the aliasing invariant of /// [`I::Aliasing`](invariant::Aliasing). /// 1. `ptr` conforms to the alignment invariant of /// [`I::Alignment`](invariant::Alignment). /// 2. `ptr` conforms to the validity invariant of /// [`I::Validity`](invariant::Validity). pub(crate) unsafe fn from_inner(ptr: PtrInner<'a, T>) -> Ptr<'a, T, I> { // SAFETY: The caller has promised to satisfy all safety invariants // of `Ptr`. Self { ptr, _invariants: PhantomData } }
/// Converts this `Ptr<T>` to a [`PtrInner<T>`]. /// /// Note that this method does not consume `self`. The caller should /// watch out for `unsafe` code which uses the returned value in a way /// that violates the safety invariants of `self`. #[inline] #[must_use] pub fn as_inner(&self) -> PtrInner<'a, T> { self.ptr } }}
#[allow(unreachable_pub)] // This is a false positive on our MSRV toolchain.pub use def::Ptr;
/// External trait implementations on [`Ptr`].mod _external { use super::*;
/// SAFETY: Shared pointers are safely `Copy`. `Ptr`'s other invariants /// (besides aliasing) are unaffected by the number of references that exist /// to `Ptr`'s referent. The notable cases are: /// - Alignment is a property of the referent type (`T`) and the address, /// both of which are unchanged /// - Let `S(T, V)` be the set of bit values permitted to appear in the /// referent of a `Ptr<T, I: Invariants<Validity = V>>`. Since this copy /// does not change `I::Validity` or `T`, `S(T, I::Validity)` is also /// unchanged. /// /// We are required to guarantee that the referents of the original `Ptr` /// and of the copy (which, of course, are actually the same since they /// live in the same byte address range) both remain in the set `S(T, /// I::Validity)`. Since this invariant holds on the original `Ptr`, it /// cannot be violated by the original `Ptr`, and thus the original `Ptr` /// cannot be used to violate this invariant on the copy. The inverse /// holds as well. impl<'a, T, I> Copy for Ptr<'a, T, I> where T: 'a + ?Sized, I: Invariants<Aliasing = Shared>, { }
/// SAFETY: See the safety comment on `Copy`. impl<'a, T, I> Clone for Ptr<'a, T, I> where T: 'a + ?Sized, I: Invariants<Aliasing = Shared>, { #[inline] fn clone(&self) -> Self { *self } }
impl<'a, T, I> Debug for Ptr<'a, T, I> where T: 'a + ?Sized, I: Invariants, { #[inline] fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result { self.as_inner().as_non_null().fmt(f) } }}
/// Methods for converting to and from `Ptr` and Rust's safe reference types.mod _conversions { use super::*; use crate::pointer::cast::{CastExact, CastSized, IdCast};
/// `&'a T` → `Ptr<'a, T>` impl<'a, T> Ptr<'a, T, (Shared, Aligned, Valid)> where T: 'a + ?Sized, { /// Constructs a `Ptr` from a shared reference. #[inline(always)] pub fn from_ref(ptr: &'a T) -> Self { let inner = PtrInner::from_ref(ptr); // SAFETY: // 0. `ptr`, by invariant on `&'a T`, conforms to the aliasing // invariant of `Shared`. // 1. `ptr`, by invariant on `&'a T`, conforms to the alignment // invariant of `Aligned`. // 2. `ptr`'s referent, by invariant on `&'a T`, is a bit-valid `T`. // This satisfies the requirement that a `Ptr<T, (_, _, Valid)>` // point to a bit-valid `T`. Even if `T` permits interior // mutation, this invariant guarantees that the returned `Ptr` // can only ever be used to modify the referent to store // bit-valid `T`s, which ensures that the returned `Ptr` cannot // be used to violate the soundness of the original `ptr: &'a T` // or of any other references that may exist to the same // referent. unsafe { Self::from_inner(inner) } } }
/// `&'a mut T` → `Ptr<'a, T>` impl<'a, T> Ptr<'a, T, (Exclusive, Aligned, Valid)> where T: 'a + ?Sized, { /// Constructs a `Ptr` from an exclusive reference. #[inline(always)] pub fn from_mut(ptr: &'a mut T) -> Self { let inner = PtrInner::from_mut(ptr); // SAFETY: // 0. `ptr`, by invariant on `&'a mut T`, conforms to the aliasing // invariant of `Exclusive`. // 1. `ptr`, by invariant on `&'a mut T`, conforms to the alignment // invariant of `Aligned`. // 2. `ptr`'s referent, by invariant on `&'a mut T`, is a bit-valid // `T`. This satisfies the requirement that a `Ptr<T, (_, _, // Valid)>` point to a bit-valid `T`. This invariant guarantees // that the returned `Ptr` can only ever be used to modify the // referent to store bit-valid `T`s, which ensures that the // returned `Ptr` cannot be used to violate the soundness of the // original `ptr: &'a mut T`. unsafe { Self::from_inner(inner) } } }
/// `Ptr<'a, T>` → `&'a T` impl<'a, T, I> Ptr<'a, T, I> where T: 'a + ?Sized, I: Invariants<Alignment = Aligned, Validity = Valid>, I::Aliasing: Reference, { /// Converts `self` to a shared reference. // This consumes `self`, not `&self`, because `self` is, logically, a // pointer. For `I::Aliasing = invariant::Shared`, `Self: Copy`, and so // this doesn't prevent the caller from still using the pointer after // calling `as_ref`. #[allow(clippy::wrong_self_convention)] #[inline] #[must_use] pub fn as_ref(self) -> &'a T { let raw = self.as_inner().as_non_null(); // SAFETY: `self` satisfies the `Aligned` invariant, so we know that // `raw` is validly-aligned for `T`. #[cfg(miri)] unsafe { crate::util::miri_promise_symbolic_alignment( raw.as_ptr().cast(), core::mem::align_of_val_raw(raw.as_ptr()), ); } // SAFETY: This invocation of `NonNull::as_ref` satisfies its // documented safety preconditions: // // 1. The pointer is properly aligned. This is ensured by-contract // on `Ptr`, because the `I::Alignment` is `Aligned`. // // 2. If the pointer's referent is not zero-sized, then the pointer // must be “dereferenceable” in the sense defined in the module // documentation; i.e.: // // > The memory range of the given size starting at the pointer // > must all be within the bounds of a single allocated object. // > [2] // // This is ensured by contract on all `PtrInner`s. // // 3. The pointer must point to a validly-initialized instance of // `T`. This is ensured by-contract on `Ptr`, because the // `I::Validity` is `Valid`. // // 4. You must enforce Rust’s aliasing rules. This is ensured by // contract on `Ptr`, because `I::Aliasing: Reference`. Either it // is `Shared` or `Exclusive`. If it is `Shared`, other // references may not mutate the referent outside of // `UnsafeCell`s. // // [1]: https://doc.rust-lang.org/std/ptr/struct.NonNull.html#method.as_ref // [2]: https://doc.rust-lang.org/std/ptr/index.html#safety unsafe { raw.as_ref() } } }
impl<'a, T, I> Ptr<'a, T, I> where T: 'a + ?Sized, I: Invariants, I::Aliasing: Reference, { /// Reborrows `self`, producing another `Ptr`. /// /// Since `self` is borrowed mutably, this prevents any methods from /// being called on `self` as long as the returned `Ptr` exists. #[inline] #[must_use] #[allow(clippy::needless_lifetimes)] // Allows us to name the lifetime in the safety comment below. pub fn reborrow<'b>(&'b mut self) -> Ptr<'b, T, I> where 'a: 'b, { // SAFETY: The following all hold by invariant on `self`, and thus // hold of `ptr = self.as_inner()`: // 0. SEE BELOW. // 1. `ptr` conforms to the alignment invariant of // [`I::Alignment`](invariant::Alignment). // 2. `ptr` conforms to the validity invariant of // [`I::Validity`](invariant::Validity). `self` and the returned // `Ptr` permit the same bit values in their referents since they // have the same referent type (`T`) and the same validity // (`I::Validity`). Thus, regardless of what mutation is // permitted (`Exclusive` aliasing or `Shared`-aliased interior // mutation), neither can be used to write a value to the // referent which violates the other's validity invariant. // // For aliasing (0 above), since `I::Aliasing: Reference`, // there are two cases for `I::Aliasing`: // - For `invariant::Shared`: `'a` outlives `'b`, and so the // returned `Ptr` does not permit accessing the referent any // longer than is possible via `self`. For shared aliasing, it is // sound for multiple `Ptr`s to exist simultaneously which // reference the same memory, so creating a new one is not // problematic. // - For `invariant::Exclusive`: Since `self` is `&'b mut` and we // return a `Ptr` with lifetime `'b`, `self` is inaccessible to // the caller for the lifetime `'b` - in other words, `self` is // inaccessible to the caller as long as the returned `Ptr` // exists. Since `self` is an exclusive `Ptr`, no other live // references or `Ptr`s may exist which refer to the same memory // while `self` is live. Thus, as long as the returned `Ptr` // exists, no other references or `Ptr`s which refer to the same // memory may be live. unsafe { Ptr::from_inner(self.as_inner()) } }
/// Reborrows `self` as shared, producing another `Ptr` with `Shared` /// aliasing. /// /// Since `self` is borrowed mutably, this prevents any methods from /// being called on `self` as long as the returned `Ptr` exists. #[inline] #[must_use] #[allow(clippy::needless_lifetimes)] // Allows us to name the lifetime in the safety comment below. pub fn reborrow_shared<'b>(&'b mut self) -> Ptr<'b, T, (Shared, I::Alignment, I::Validity)> where 'a: 'b, { // SAFETY: The following all hold by invariant on `self`, and thus // hold of `ptr = self.as_inner()`: // 0. SEE BELOW. // 1. `ptr` conforms to the alignment invariant of // [`I::Alignment`](invariant::Alignment). // 2. `ptr` conforms to the validity invariant of // [`I::Validity`](invariant::Validity). `self` and the returned // `Ptr` permit the same bit values in their referents since they // have the same referent type (`T`) and the same validity // (`I::Validity`). Thus, regardless of what mutation is // permitted (`Exclusive` aliasing or `Shared`-aliased interior // mutation), neither can be used to write a value to the // referent which violates the other's validity invariant. // // For aliasing (0 above), since `I::Aliasing: Reference`, // there are two cases for `I::Aliasing`: // - For `invariant::Shared`: `'a` outlives `'b`, and so the // returned `Ptr` does not permit accessing the referent any // longer than is possible via `self`. For shared aliasing, it is // sound for multiple `Ptr`s to exist simultaneously which // reference the same memory, so creating a new one is not // problematic. // - For `invariant::Exclusive`: Since `self` is `&'b mut` and we // return a `Ptr` with lifetime `'b`, `self` is inaccessible to // the caller for the lifetime `'b` - in other words, `self` is // inaccessible to the caller as long as the returned `Ptr` // exists. Since `self` is an exclusive `Ptr`, no other live // references or `Ptr`s may exist which refer to the same memory // while `self` is live. Thus, as long as the returned `Ptr` // exists, no other references or `Ptr`s which refer to the same // memory may be live. unsafe { Ptr::from_inner(self.as_inner()) } } }
/// `Ptr<'a, T>` → `&'a mut T` impl<'a, T> Ptr<'a, T, (Exclusive, Aligned, Valid)> where T: 'a + ?Sized, { /// Converts `self` to a mutable reference. #[allow(clippy::wrong_self_convention)] #[inline] #[must_use] pub fn as_mut(self) -> &'a mut T { let mut raw = self.as_inner().as_non_null(); // SAFETY: `self` satisfies the `Aligned` invariant, so we know that // `raw` is validly-aligned for `T`. #[cfg(miri)] unsafe { crate::util::miri_promise_symbolic_alignment( raw.as_ptr().cast(), core::mem::align_of_val_raw(raw.as_ptr()), ); } // SAFETY: This invocation of `NonNull::as_mut` satisfies its // documented safety preconditions: // // 1. The pointer is properly aligned. This is ensured by-contract // on `Ptr`, because the `ALIGNMENT_INVARIANT` is `Aligned`. // // 2. If the pointer's referent is not zero-sized, then the pointer // must be “dereferenceable” in the sense defined in the module // documentation; i.e.: // // > The memory range of the given size starting at the pointer // > must all be within the bounds of a single allocated object. // > [2] // // This is ensured by contract on all `PtrInner`s. // // 3. The pointer must point to a validly-initialized instance of // `T`. This is ensured by-contract on `Ptr`, because the // validity invariant is `Valid`. // // 4. You must enforce Rust’s aliasing rules. This is ensured by // contract on `Ptr`, because the `ALIASING_INVARIANT` is // `Exclusive`. // // [1]: https://doc.rust-lang.org/std/ptr/struct.NonNull.html#method.as_mut // [2]: https://doc.rust-lang.org/std/ptr/index.html#safety unsafe { raw.as_mut() } } }
/// `Ptr<'a, T>` → `Ptr<'a, U>` impl<'a, T: ?Sized, I> Ptr<'a, T, I> where I: Invariants, { #[must_use] #[inline(always)] pub fn transmute<U, V, R>(self) -> Ptr<'a, U, (I::Aliasing, Unaligned, V)> where V: Validity, U: TransmuteFromPtr<T, I::Aliasing, I::Validity, V, <U as SizeEq<T>>::CastFrom, R> + SizeEq<T> + ?Sized, { self.transmute_with::<U, V, <U as SizeEq<T>>::CastFrom, R>() }
#[inline] #[must_use] pub fn transmute_with<U, V, C, R>(self) -> Ptr<'a, U, (I::Aliasing, Unaligned, V)> where V: Validity, U: TransmuteFromPtr<T, I::Aliasing, I::Validity, V, C, R> + ?Sized, C: CastExact<T, U>, { // SAFETY: // - By `C: CastExact`, `C` preserves referent address, and so we // don't need to consider projections in the following safety // arguments. // - If aliasing is `Shared`, then by `U: TransmuteFromPtr<T>`, at // least one of the following holds: // - `T: Immutable` and `U: Immutable`, in which case it is // trivially sound for shared code to operate on a `&T` and `&U` // at the same time, as neither can perform interior mutation // - It is directly guaranteed that it is sound for shared code to // operate on these references simultaneously // - By `U: TransmuteFromPtr<T, I::Aliasing, I::Validity, C, V>`, it // is sound to perform this transmute using `C`. unsafe { self.project_transmute_unchecked::<_, _, C>() } }
#[inline] #[must_use] pub fn recall_validity<V, R>(self) -> Ptr<'a, T, (I::Aliasing, I::Alignment, V)> where V: Validity, T: TransmuteFromPtr<T, I::Aliasing, I::Validity, V, IdCast, R>, { let ptr = self.transmute_with::<T, V, IdCast, R>(); // SAFETY: `self` and `ptr` have the same address and referent type. // Therefore, if `self` satisfies `I::Alignment`, then so does // `ptr`. unsafe { ptr.assume_alignment::<I::Alignment>() } }
/// Projects and/or transmutes to a different (unsized) referent type /// without checking interior mutability. /// /// Callers should prefer [`cast`] or [`project`] where possible. /// /// [`cast`]: Ptr::cast /// [`project`]: Ptr::project /// /// # Safety /// /// The caller promises that: /// - If `I::Aliasing` is [`Shared`], it must not be possible for safe /// code, operating on a `&T` and `&U`, with the referents of `self` /// and `self.project_transmute_unchecked()`, respectively, to cause /// undefined behavior. /// - It is sound to project and/or transmute a pointer of type `T` with /// aliasing `I::Aliasing` and validity `I::Validity` to a pointer of /// type `U` with aliasing `I::Aliasing` and validity `V`. This is a /// subtle soundness requirement that is a function of `T`, `U`, /// `I::Aliasing`, `I::Validity`, and `V`, and may depend upon the /// presence, absence, or specific location of `UnsafeCell`s in `T` /// and/or `U`, and on whether interior mutation is ever permitted via /// those `UnsafeCell`s. See [`Validity`] for more details. #[inline] #[must_use] pub unsafe fn project_transmute_unchecked<U: ?Sized, V, P>( self, ) -> Ptr<'a, U, (I::Aliasing, Unaligned, V)> where V: Validity, P: crate::pointer::cast::Project<T, U>, { let ptr = self.as_inner().project::<_, P>();
// SAFETY: // // The following safety arguments rely on the fact that `P: Project` // guarantees that `P` is a referent-preserving or -shrinking // projection. Thus, `ptr` addresses a subset of the bytes of // `*self`, and so certain properties that hold of `*self` also hold // of `*ptr`. // // 0. `ptr` conforms to the aliasing invariant of `I::Aliasing`: // - `Exclusive`: `self` is the only `Ptr` or reference which is // permitted to read or modify the referent for the lifetime // `'a`. Since we consume `self` by value, the returned pointer // remains the only `Ptr` or reference which is permitted to // read or modify the referent for the lifetime `'a`. // - `Shared`: Since `self` has aliasing `Shared`, we know that // no other code may mutate the referent during the lifetime // `'a`, except via `UnsafeCell`s, and except as permitted by // `T`'s library safety invariants. The caller promises that // any safe operations which can be permitted on a `&T` and a // `&U` simultaneously must be sound. Thus, no operations on a // `&U` could violate `&T`'s library safety invariants, and // vice-versa. Since any mutation via shared references outside // of `UnsafeCell`s is unsound, this must be impossible using // `&T` and `&U`. // - `Inaccessible`: There are no restrictions we need to uphold. // 1. `ptr` trivially satisfies the alignment invariant `Unaligned`. // 2. The caller promises that the returned pointer satisfies the // validity invariant `V` with respect to its referent type, `U`. unsafe { Ptr::from_inner(ptr) } } }
/// `Ptr<'a, T, (_, _, _)>` → `Ptr<'a, Unalign<T>, (_, Aligned, _)>` impl<'a, T, I> Ptr<'a, T, I> where I: Invariants, { /// Converts a `Ptr` an unaligned `T` into a `Ptr` to an aligned /// `Unalign<T>`. #[inline] #[must_use] pub fn into_unalign( self, ) -> Ptr<'a, crate::Unalign<T>, (I::Aliasing, Aligned, I::Validity)> { // FIXME(#1359): This should be a `transmute_with` call. // Unfortunately, to avoid blanket impl conflicts, we only implement // `TransmuteFrom<T>` for `Unalign<T>` (and vice versa) specifically // for `Valid` validity, not for all validity types.
// SAFETY: // - By `CastSized: Cast`, `CastSized` preserves referent address, // and so we don't need to consider projections in the following // safety arguments. // - Since `Unalign<T>` has the same layout as `T`, the returned // pointer refers to `UnsafeCell`s at the same locations as // `self`. // - `Unalign<T>` promises to have the same bit validity as `T`. By // invariant on `Validity`, the set of bit patterns allowed in the // referent of a `Ptr<X, (_, _, V)>` is only a function of the // validity of `X` and of `V`. Thus, the set of bit patterns // allowed in the referent of a `Ptr<T, (_, _, I::Validity)>` is // the same as the set of bit patterns allowed in the referent of // a `Ptr<Unalign<T>, (_, _, I::Validity)>`. As a result, `self` // and the returned `Ptr` permit the same set of bit patterns in // their referents, and so neither can be used to violate the // validity of the other. let ptr = unsafe { self.project_transmute_unchecked::<_, _, CastSized>() }; ptr.bikeshed_recall_aligned() } }
impl<'a, T, I> Ptr<'a, T, I> where T: ?Sized, I: Invariants<Validity = Valid>, I::Aliasing: Reference, { /// Reads the referent. #[must_use] #[inline(always)] pub fn read<R>(self) -> T where T: Copy, T: Read<I::Aliasing, R>, { <I::Alignment as Alignment>::read(self) }
/// Views the value as an aligned reference. /// /// This is only available if `T` is [`Unaligned`]. #[must_use] #[inline] pub fn unaligned_as_ref(self) -> &'a T where T: crate::Unaligned, { self.bikeshed_recall_aligned().as_ref() } }}
/// State transitions between invariants.mod _transitions { use super::*; use crate::{ pointer::{cast::IdCast, transmute::TryTransmuteFromPtr}, ReadOnly, };
impl<'a, T, I> Ptr<'a, T, I> where T: 'a + ?Sized, I: Invariants, { /// Assumes that `self` satisfies the invariants `H`. /// /// # Safety /// /// The caller promises that `self` satisfies the invariants `H`. unsafe fn assume_invariants<H: Invariants>(self) -> Ptr<'a, T, H> { // SAFETY: The caller has promised to satisfy all parameterized // invariants of `Ptr`. `Ptr`'s other invariants are satisfied // by-contract by the source `Ptr`. unsafe { Ptr::from_inner(self.as_inner()) } }
/// Helps the type system unify two distinct invariant types which are /// actually the same. #[inline] #[must_use] pub fn unify_invariants< H: Invariants<Aliasing = I::Aliasing, Alignment = I::Alignment, Validity = I::Validity>, >( self, ) -> Ptr<'a, T, H> { // SAFETY: The associated type bounds on `H` ensure that the // invariants are unchanged. unsafe { self.assume_invariants::<H>() } }
/// Assumes that `self`'s referent is validly-aligned for `T` if /// required by `A`. /// /// # Safety /// /// The caller promises that `self`'s referent conforms to the alignment /// invariant of `T` if required by `A`. #[inline] pub(crate) unsafe fn assume_alignment<A: Alignment>( self, ) -> Ptr<'a, T, (I::Aliasing, A, I::Validity)> { // SAFETY: The caller promises that `self`'s referent is // well-aligned for `T` if required by `A` . unsafe { self.assume_invariants() } }
/// Checks the `self`'s alignment at runtime, returning an aligned `Ptr` /// on success. #[inline] pub fn try_into_aligned( self, ) -> Result<Ptr<'a, T, (I::Aliasing, Aligned, I::Validity)>, AlignmentError<Self, T>> where T: Sized, { if let Err(err) = crate::util::validate_aligned_to::<_, T>(self.as_inner().as_non_null()) { return Err(err.with_src(self)); }
// SAFETY: We just checked the alignment. Ok(unsafe { self.assume_alignment::<Aligned>() }) }
/// Recalls that `self`'s referent is validly-aligned for `T`. #[inline] // FIXME(#859): Reconsider the name of this method before making it // public. #[must_use] pub fn bikeshed_recall_aligned(self) -> Ptr<'a, T, (I::Aliasing, Aligned, I::Validity)> where T: crate::Unaligned, { // SAFETY: The bound `T: Unaligned` ensures that `T` has no // non-trivial alignment requirement. unsafe { self.assume_alignment::<Aligned>() } }
/// Assumes that `self`'s referent conforms to the validity requirement /// of `V`. /// /// # Safety /// /// The caller promises that `self`'s referent conforms to the validity /// requirement of `V`. #[must_use] #[inline] pub unsafe fn assume_validity<V: Validity>( self, ) -> Ptr<'a, T, (I::Aliasing, I::Alignment, V)> { // SAFETY: The caller promises that `self`'s referent conforms to // the validity requirement of `V`. unsafe { self.assume_invariants() } }
/// A shorthand for `self.assume_validity<invariant::Initialized>()`. /// /// # Safety /// /// The caller promises to uphold the safety preconditions of /// `self.assume_validity<invariant::Initialized>()`. #[must_use] #[inline] pub unsafe fn assume_initialized( self, ) -> Ptr<'a, T, (I::Aliasing, I::Alignment, Initialized)> { // SAFETY: The caller has promised to uphold the safety // preconditions. unsafe { self.assume_validity::<Initialized>() } }
/// A shorthand for `self.assume_validity<Valid>()`. /// /// # Safety /// /// The caller promises to uphold the safety preconditions of /// `self.assume_validity<Valid>()`. #[must_use] #[inline] pub unsafe fn assume_valid(self) -> Ptr<'a, T, (I::Aliasing, I::Alignment, Valid)> { // SAFETY: The caller has promised to uphold the safety // preconditions. unsafe { self.assume_validity::<Valid>() } }
/// Checks that `self`'s referent is validly initialized for `T`, /// returning a `Ptr` with `Valid` on success. /// /// # Panics /// /// This method will panic if /// [`T::is_bit_valid`][TryFromBytes::is_bit_valid] panics. /// /// # Safety /// /// On error, unsafe code may rely on this method's returned /// `ValidityError` containing `self`. #[inline] pub fn try_into_valid<R, S>( mut self, ) -> Result<Ptr<'a, T, (I::Aliasing, I::Alignment, Valid)>, ValidityError<Self, T>> where T: TryFromBytes + Read<I::Aliasing, R> + TryTransmuteFromPtr<T, I::Aliasing, I::Validity, Valid, IdCast, S>, ReadOnly<T>: Read<I::Aliasing, R>, I::Aliasing: Reference, I: Invariants<Validity = Initialized>, { // This call may panic. If that happens, it doesn't cause any // soundness issues, as we have not generated any invalid state // which we need to fix before returning. if T::is_bit_valid(self.reborrow().transmute::<_, _, _>().reborrow_shared()) { // SAFETY: If `T::is_bit_valid`, code may assume that `self` // contains a bit-valid instance of `T`. By `T: // TryTransmuteFromPtr<T, I::Aliasing, I::Validity, Valid>`, so // long as `self`'s referent conforms to the `Valid` validity // for `T` (which we just confirmed), then this transmute is // sound. Ok(unsafe { self.assume_valid() }) } else { Err(ValidityError::new(self)) } }
/// Forgets that `self`'s referent is validly-aligned for `T`. #[inline] #[must_use] pub fn forget_aligned(self) -> Ptr<'a, T, (I::Aliasing, Unaligned, I::Validity)> { // SAFETY: `Unaligned` is less restrictive than `Aligned`. unsafe { self.assume_invariants() } } }}
/// Casts of the referent type.#[cfg_attr(not(zerocopy_unstable_ptr), allow(unreachable_pub))]pub use _casts::TryWithError;mod _casts { use core::cell::UnsafeCell;
use super::*; use crate::{ pointer::cast::{AsBytesCast, Cast}, HasTag, ProjectField, };
impl<'a, T, I> Ptr<'a, T, I> where T: 'a + ?Sized, I: Invariants, { /// Casts to a different referent type without checking interior /// mutability. /// /// Callers should prefer [`cast`][Ptr::cast] where possible. /// /// # Safety /// /// If `I::Aliasing` is [`Shared`], it must not be possible for safe /// code, operating on a `&T` and `&U` with the same referent /// simultaneously, to cause undefined behavior. #[inline] #[must_use] pub unsafe fn cast_unchecked<U, C: Cast<T, U>>( self, ) -> Ptr<'a, U, (I::Aliasing, Unaligned, I::Validity)> where U: 'a + CastableFrom<T, I::Validity, I::Validity> + ?Sized, { // SAFETY: // - By `C: Cast`, `C` preserves the address of the referent. // - If `I::Aliasing` is [`Shared`], the caller promises that it // is not possible for safe code, operating on a `&T` and `&U` // with the same referent simultaneously, to cause undefined // behavior. // - By `U: CastableFrom<T, I::Validity, I::Validity>`, // `I::Validity` is either `Uninit` or `Initialized`. In both // cases, the bit validity `I::Validity` has the same semantics // regardless of referent type. In other words, the set of allowed // referent values for `Ptr<T, (_, _, I::Validity)>` and `Ptr<U, // (_, _, I::Validity)>` are identical. As a consequence, neither // `self` nor the returned `Ptr` can be used to write values which // are invalid for the other. unsafe { self.project_transmute_unchecked::<_, _, C>() } }
/// Casts to a different referent type. #[inline] #[must_use] pub fn cast<U, C, R>(self) -> Ptr<'a, U, (I::Aliasing, Unaligned, I::Validity)> where T: MutationCompatible<U, I::Aliasing, I::Validity, I::Validity, R>, U: 'a + ?Sized + CastableFrom<T, I::Validity, I::Validity>, C: Cast<T, U>, { // SAFETY: Because `T: MutationCompatible<U, I::Aliasing, R>`, one // of the following holds: // - `T: Read<I::Aliasing>` and `U: Read<I::Aliasing>`, in which // case one of the following holds: // - `I::Aliasing` is `Exclusive` // - `T` and `U` are both `Immutable` // - It is sound for safe code to operate on `&T` and `&U` with the // same referent simultaneously. unsafe { self.cast_unchecked::<_, C>() } }
#[inline(always)] pub fn project<F, const VARIANT_ID: i128, const FIELD_ID: i128>( mut self, ) -> Result<Ptr<'a, T::Type, T::Invariants>, T::Error> where T: ProjectField<F, I, VARIANT_ID, FIELD_ID>, I::Aliasing: Reference, { use crate::pointer::cast::Projection; match T::is_projectable(self.reborrow().project_tag()) { Ok(()) => { let inner = self.as_inner(); let projected = inner.project::<_, Projection<F, VARIANT_ID, FIELD_ID>>(); // SAFETY: By `T: ProjectField<F, I, VARIANT_ID, FIELD_ID>`, // for `self: Ptr<'_, T, I>` such that `T::is_projectable` // (which we've verified in this match arm), // `T::project(self.as_inner())` conforms to // `T::Invariants`. The `projected` pointer satisfies these // invariants because it is produced by way of an // abstraction that is equivalent to // `T::project(ptr.as_inner())`: by invariant on // `PtrInner::project`, `projected` is guaranteed to address // the subset of the bytes of `inner`'s referent addressed // by `Projection::project(inner)`, and by invariant on // `Projection`, `Projection::project` is implemented by // delegating to an implementation of `HasField::project`. Ok(unsafe { Ptr::from_inner(projected) }) } Err(err) => Err(err), } }
#[must_use] #[inline(always)] pub(crate) fn project_tag(self) -> Ptr<'a, T::Tag, I> where T: HasTag, { // SAFETY: By invariant on `Self::ProjectToTag`, this is a sound // projection. let tag = unsafe { self.project_transmute_unchecked::<_, _, T::ProjectToTag>() }; // SAFETY: By invariant on `Self::ProjectToTag`, the projected // pointer has the same alignment as `ptr`. let tag = unsafe { tag.assume_alignment() }; tag.unify_invariants() }
/// Attempts to transform the pointer, restoring the original on /// failure. /// /// # Safety /// /// If `I::Aliasing != Shared`, then if `f` returns `Err(err)`, no copy /// of `f`'s argument must exist outside of `err`. #[inline(always)] pub(crate) unsafe fn try_with_unchecked<U, J, E, F>( self, f: F, ) -> Result<Ptr<'a, U, J>, E::Mapped> where U: 'a + ?Sized, J: Invariants<Aliasing = I::Aliasing>, E: TryWithError<Self>, F: FnOnce(Ptr<'a, T, I>) -> Result<Ptr<'a, U, J>, E>, { let old_inner = self.as_inner(); #[rustfmt::skip] let res = f(self).map_err(#[inline(always)] move |err: E| { err.map(#[inline(always)] |src| { drop(src);
// SAFETY: // 0. Aliasing is either `Shared` or `Exclusive`: // - If aliasing is `Shared`, then it cannot violate // aliasing make another copy of this pointer (in fact, // using `I::Aliasing = Shared`, we could have just // cloned `self`). // - If aliasing is `Exclusive`, then `f` is not allowed // to make another copy of `self`. In `map_err`, we are // consuming the only value in the returned `Result`. // By invariant on `E: TryWithError<Self>`, that `err: // E` only contains a single `Self` and no other // non-ZST fields which could be `Ptr`s or references // to `self`'s referent. By the same invariant, `map` // consumes this single `Self` and passes it to this // closure. Since `self` was, by invariant on // `Exclusive`, the only `Ptr` or reference live for // `'a` with this referent, and since we `drop(src)` // above, there are no copies left, and so we are // creating the only copy. // 1. `self` conforms to `I::Aliasing` by invariant on // `Ptr`, and `old_inner` has the same address, so it // does too. // 2. `f` could not have violated `self`'s validity without // itself being unsound. Assuming that `f` is sound, the // referent of `self` is still valid for `T`. unsafe { Ptr::from_inner(old_inner) } }) }); res }
/// Attempts to transform the pointer, restoring the original on /// failure. #[inline(always)] pub fn try_with<U, J, E, F>(self, f: F) -> Result<Ptr<'a, U, J>, E::Mapped> where U: 'a + ?Sized, J: Invariants<Aliasing = I::Aliasing>, E: TryWithError<Self>, F: FnOnce(Ptr<'a, T, I>) -> Result<Ptr<'a, U, J>, E>, I: Invariants<Aliasing = Shared>, { // SAFETY: `I::Aliasing = Shared`, so the safety condition does not // apply. unsafe { self.try_with_unchecked(f) } } }
/// # Safety /// /// `Self` only contains a single `Self::Inner`, and `Self::Mapped` only /// contains a single `MappedInner`. Other than that, `Self` and /// `Self::Mapped` contain no non-ZST fields. /// /// `map` must pass ownership of `self`'s sole `Self::Inner` to `f`. pub unsafe trait TryWithError<MappedInner> { type Inner; type Mapped; fn map<F: FnOnce(Self::Inner) -> MappedInner>(self, f: F) -> Self::Mapped; }
impl<'a, T, I> Ptr<'a, T, I> where T: 'a + KnownLayout + ?Sized, I: Invariants, { /// Casts this pointer-to-initialized into a pointer-to-bytes. #[allow(clippy::wrong_self_convention)] #[must_use] #[inline] pub fn as_bytes<R>(self) -> Ptr<'a, [u8], (I::Aliasing, Aligned, Valid)> where [u8]: TransmuteFromPtr<T, I::Aliasing, I::Validity, Valid, AsBytesCast, R>, { self.transmute_with::<[u8], Valid, AsBytesCast, _>().bikeshed_recall_aligned() } }
impl<'a, T, I, const N: usize> Ptr<'a, [T; N], I> where T: 'a, I: Invariants, { /// Casts this pointer-to-array into a slice. #[allow(clippy::wrong_self_convention)] #[inline] #[must_use] pub fn as_slice(self) -> Ptr<'a, [T], I> { let slice = self.as_inner().as_slice(); // SAFETY: Note that, by post-condition on `PtrInner::as_slice`, // `slice` refers to the same byte range as `self.as_inner()`. // // 0. Thus, `slice` conforms to the aliasing invariant of // `I::Aliasing` because `self` does. // 1. By the above lemma, `slice` conforms to the alignment // invariant of `I::Alignment` because `self` does. // 2. Since `[T; N]` and `[T]` have the same bit validity [1][2], // and since `self` and the returned `Ptr` have the same validity // invariant, neither `self` nor the returned `Ptr` can be used // to write a value to the referent which violates the other's // validity invariant. // // [1] Per https://doc.rust-lang.org/1.81.0/reference/type-layout.html#array-layout: // // An array of `[T; N]` has a size of `size_of::<T>() * N` and the // same alignment of `T`. Arrays are laid out so that the // zero-based `nth` element of the array is offset from the start // of the array by `n * size_of::<T>()` bytes. // // ... // // Slices have the same layout as the section of the array they // slice. // // [2] Per https://doc.rust-lang.org/1.81.0/reference/types/array.html#array-types: // // All elements of arrays are always initialized unsafe { Ptr::from_inner(slice) } } }
/// For caller convenience, these methods are generic over alignment /// invariant. In practice, the referent is always well-aligned, because the /// alignment of `[u8]` is 1. impl<'a, I> Ptr<'a, [u8], I> where I: Invariants<Validity = Valid>, { /// Attempts to cast `self` to a `U` using the given cast type. /// /// If `U` is a slice DST and pointer metadata (`meta`) is provided, /// then the cast will only succeed if it would produce an object with /// the given metadata. /// /// Returns `None` if the resulting `U` would be invalidly-aligned, if /// no `U` can fit in `self`, or if the provided pointer metadata /// describes an invalid instance of `U`. On success, returns a pointer /// to the largest-possible `U` which fits in `self`. /// /// # Safety /// /// The caller may assume that this implementation is correct, and may /// rely on that assumption for the soundness of their code. In /// particular, the caller may assume that, if `try_cast_into` returns /// `Some((ptr, remainder))`, then `ptr` and `remainder` refer to /// non-overlapping byte ranges within `self`, and that `ptr` and /// `remainder` entirely cover `self`. Finally: /// - If this is a prefix cast, `ptr` has the same address as `self`. /// - If this is a suffix cast, `remainder` has the same address as /// `self`. #[inline(always)] pub fn try_cast_into<U, R>( self, cast_type: CastType, meta: Option<U::PointerMetadata>, ) -> Result< (Ptr<'a, U, (I::Aliasing, Aligned, Initialized)>, Ptr<'a, [u8], I>), CastError<Self, U>, > where I::Aliasing: Reference, U: 'a + ?Sized + KnownLayout + Read<I::Aliasing, R>, { let (inner, remainder) = self.as_inner().try_cast_into(cast_type, meta).map_err( #[inline(always)] |err| { err.map_src( #[inline(always)] |inner| // SAFETY: `PtrInner::try_cast_into` promises to return its // original argument on error, which was originally produced // by `self.as_inner()`, which is guaranteed to satisfy // `Ptr`'s invariants. unsafe { Ptr::from_inner(inner) }, ) }, )?;
// SAFETY: // 0. Since `U: Read<I::Aliasing, _>`, either: // - `I::Aliasing` is `Exclusive`, in which case both `src` and // `ptr` conform to `Exclusive` // - `I::Aliasing` is `Shared` and `U` is `Immutable` (we already // know that `[u8]: Immutable`). In this case, neither `U` nor // `[u8]` permit mutation, and so `Shared` aliasing is // satisfied. // 1. `ptr` conforms to the alignment invariant of `Aligned` because // it is derived from `try_cast_into`, which promises that the // object described by `target` is validly aligned for `U`. // 2. By trait bound, `self` - and thus `target` - is a bit-valid // `[u8]`. `Ptr<[u8], (_, _, Valid)>` and `Ptr<_, (_, _, // Initialized)>` have the same bit validity, and so neither // `self` nor `res` can be used to write a value to the referent // which violates the other's validity invariant. let res = unsafe { Ptr::from_inner(inner) };
// SAFETY: // 0. `self` and `remainder` both have the type `[u8]`. Thus, they // have `UnsafeCell`s at the same locations. Type casting does // not affect aliasing. // 1. `[u8]` has no alignment requirement. // 2. `self` has validity `Valid` and has type `[u8]`. Since // `remainder` references a subset of `self`'s referent, it is // also a bit-valid `[u8]`. Thus, neither `self` nor `remainder` // can be used to write a value to the referent which violates // the other's validity invariant. let remainder = unsafe { Ptr::from_inner(remainder) };
Ok((res, remainder)) }
/// Attempts to cast `self` into a `U`, failing if all of the bytes of /// `self` cannot be treated as a `U`. /// /// In particular, this method fails if `self` is not validly-aligned /// for `U` or if `self`'s size is not a valid size for `U`. /// /// # Safety /// /// On success, the caller may assume that the returned pointer /// references the same byte range as `self`. #[allow(unused)] #[inline(always)] pub fn try_cast_into_no_leftover<U, R>( self, meta: Option<U::PointerMetadata>, ) -> Result<Ptr<'a, U, (I::Aliasing, Aligned, Initialized)>, CastError<Self, U>> where I::Aliasing: Reference, U: 'a + ?Sized + KnownLayout + Read<I::Aliasing, R>, [u8]: Read<I::Aliasing, R>, { // SAFETY: The provided closure returns the only copy of `slf`. unsafe { self.try_with_unchecked( #[inline(always)] |slf| match slf.try_cast_into(CastType::Prefix, meta) { Ok((slf, remainder)) => { if remainder.is_empty() { Ok(slf) } else { Err(CastError::Size(SizeError::<_, U>::new(()))) } } Err(err) => Err(err.map_src( #[inline(always)] |_slf| (), )), }, ) } } }
impl<'a, T, I> Ptr<'a, UnsafeCell<T>, I> where T: 'a + ?Sized, I: Invariants<Aliasing = Exclusive>, { /// Converts this `Ptr` into a pointer to the underlying data. /// /// This call borrows the `UnsafeCell` mutably (at compile-time) which /// guarantees that we possess the only reference. /// /// This is like [`UnsafeCell::get_mut`], but for `Ptr`. /// /// [`UnsafeCell::get_mut`]: core::cell::UnsafeCell::get_mut #[must_use] #[inline(always)] pub fn get_mut(self) -> Ptr<'a, T, I> { // SAFETY: As described below, `UnsafeCell<T>` has the same size // as `T: ?Sized` (same static size or same DST layout). Thus, // `*const UnsafeCell<T> as *const T` is a size-preserving cast. define_cast!(unsafe { Cast<T: ?Sized> = UnsafeCell<T> => T });
// SAFETY: // - Aliasing is `Exclusive`, and so we are not required to promise // anything about the locations of `UnsafeCell`s. // - `UnsafeCell<T>` has the same bit validity as `T` [1]. // Technically the term "representation" doesn't guarantee this, // but the subsequent sentence in the documentation makes it clear // that this is the intention. // // By invariant on `Validity`, since `T` and `UnsafeCell<T>` have // the same bit validity, then the set of values which may appear // in the referent of a `Ptr<T, (_, _, V)>` is the same as the set // which may appear in the referent of a `Ptr<UnsafeCell<T>, (_, // _, V)>`. Thus, neither `self` nor `ptr` may be used to write a // value to the referent which would violate the other's validity // invariant. // // [1] Per https://doc.rust-lang.org/1.81.0/core/cell/struct.UnsafeCell.html#memory-layout: // // `UnsafeCell<T>` has the same in-memory representation as its // inner type `T`. A consequence of this guarantee is that it is // possible to convert between `T` and `UnsafeCell<T>`. let ptr = unsafe { self.project_transmute_unchecked::<_, _, Cast>() };
// SAFETY: `UnsafeCell<T>` has the same alignment as `T` [1], // and so if `self` is guaranteed to be aligned, then so is the // returned `Ptr`. // // [1] Per https://doc.rust-lang.org/1.81.0/core/cell/struct.UnsafeCell.html#memory-layout: // // `UnsafeCell<T>` has the same in-memory representation as // its inner type `T`. A consequence of this guarantee is that // it is possible to convert between `T` and `UnsafeCell<T>`. let ptr = unsafe { ptr.assume_alignment::<I::Alignment>() }; ptr.unify_invariants() } }}
/// Projections through the referent.mod _project { use super::*;
impl<'a, T, I> Ptr<'a, [T], I> where T: 'a, I: Invariants, I::Aliasing: Reference, { /// Iteratively projects the elements `Ptr<T>` from `Ptr<[T]>`. #[inline] pub fn iter(self) -> impl Iterator<Item = Ptr<'a, T, I>> { // SAFETY: // 0. `elem` conforms to the aliasing invariant of `I::Aliasing`: // - `Exclusive`: `self` is consumed by value, and therefore // cannot be used to access the slice while any yielded // element `Ptr` is live. Each non-zero-sized element is a // disjoint byte range within the slice, and zero-sized // elements address no bytes, so distinct yielded element // `Ptr`s do not alias each other. // - `Shared`: It is sound for multiple shared `Ptr`s to exist // simultaneously which reference the same memory. // 1. `elem`, conditionally, conforms to the validity invariant of // `I::Alignment`. If `elem` is projected from data well-aligned // for `[T]`, `elem` will be valid for `T`. // 2. `elem` conforms to the validity invariant of `I::Validity`. // Per https://doc.rust-lang.org/1.81.0/reference/type-layout.html#array-layout: // // Slices have the same layout as the section of the array they // slice. // // Arrays are laid out so that the zero-based `nth` element of // the array is offset from the start of the array by `n * // size_of::<T>()` bytes. Thus, `elem` addresses a valid `T` // within the slice. Since `self` satisfies `I::Validity`, `elem` // also satisfies `I::Validity`. self.as_inner().iter().map( #[inline(always)] |elem| unsafe { Ptr::from_inner(elem) }, ) } }
#[allow(clippy::needless_lifetimes)] impl<'a, T, I> Ptr<'a, T, I> where T: 'a + ?Sized + KnownLayout<PointerMetadata = usize>, I: Invariants, { /// The number of slice elements in the object referenced by `self`. #[inline] #[must_use] pub fn len(&self) -> usize { self.as_inner().meta().get() }
/// Returns `true` if the slice pointer has a length of 0. #[inline] #[must_use] pub fn is_empty(&self) -> bool { self.len() == 0 } }}
#[cfg(test)]mod tests { use core::mem::{self, MaybeUninit};
use super::*; #[allow(unused)] // Needed on our MSRV, but considered unused on later toolchains. use crate::util::AsAddress; use crate::{pointer::BecauseImmutable, util::testutil::AU64, FromBytes, Immutable};
mod test_ptr_try_cast_into_soundness { use super::*;
// This test is designed so that if `Ptr::try_cast_into_xxx` are // buggy, it will manifest as unsoundness that Miri can detect.
// - If `size_of::<T>() == 0`, `N == 4` // - Else, `N == 4 * size_of::<T>()` // // Each test will be run for each metadata in `metas`. fn test<T, I, const N: usize>(metas: I) where T: ?Sized + KnownLayout + Immutable + FromBytes, I: IntoIterator<Item = Option<T::PointerMetadata>> + Clone, { let mut bytes = [MaybeUninit::<u8>::uninit(); N]; let initialized = [MaybeUninit::new(0u8); N]; for start in 0..=bytes.len() { for end in start..=bytes.len() { // Set all bytes to uninitialized other than those in // the range we're going to pass to `try_cast_from`. // This allows Miri to detect out-of-bounds reads // because they read uninitialized memory. Without this, // some out-of-bounds reads would still be in-bounds of // `bytes`, and so might spuriously be accepted. bytes = [MaybeUninit::<u8>::uninit(); N]; let bytes = &mut bytes[start..end]; // Initialize only the byte range we're going to pass to // `try_cast_from`. bytes.copy_from_slice(&initialized[start..end]);
let bytes = { let bytes: *const [MaybeUninit<u8>] = bytes; #[allow(clippy::as_conversions)] let bytes = bytes as *const [u8]; // SAFETY: We just initialized these bytes to valid // `u8`s. unsafe { &*bytes } };
// SAFETY: The bytes in `slf` must be initialized. unsafe fn validate_and_get_len< T: ?Sized + KnownLayout + FromBytes + Immutable, >( slf: Ptr<'_, T, (Shared, Aligned, Initialized)>, ) -> usize { let t = slf.recall_validity().as_ref();
let bytes = { let len = mem::size_of_val(t); let t: *const T = t; // SAFETY: // - We know `t`'s bytes are all initialized // because we just read it from `slf`, which // points to an initialized range of bytes. If // there's a bug and this doesn't hold, then // that's exactly what we're hoping Miri will // catch! // - Since `T: FromBytes`, `T` doesn't contain // any `UnsafeCell`s, so it's okay for `t: T` // and a `&[u8]` to the same memory to be // alive concurrently. unsafe { core::slice::from_raw_parts(t.cast::<u8>(), len) } };
// This assertion ensures that `t`'s bytes are read // and compared to another value, which in turn // ensures that Miri gets a chance to notice if any // of `t`'s bytes are uninitialized, which they // shouldn't be (see the comment above). assert_eq!(bytes, vec![0u8; bytes.len()]);
mem::size_of_val(t) }
for meta in metas.clone().into_iter() { for cast_type in [CastType::Prefix, CastType::Suffix] { if let Ok((slf, remaining)) = Ptr::from_ref(bytes) .try_cast_into::<T, BecauseImmutable>(cast_type, meta) { // SAFETY: All bytes in `bytes` have been // initialized. let len = unsafe { validate_and_get_len(slf) }; assert_eq!(remaining.len(), bytes.len() - len); #[allow(unstable_name_collisions)] let bytes_addr = bytes.as_ptr().addr(); #[allow(unstable_name_collisions)] let remaining_addr = remaining.as_inner().as_ptr().addr(); match cast_type { CastType::Prefix => { assert_eq!(remaining_addr, bytes_addr + len) } CastType::Suffix => assert_eq!(remaining_addr, bytes_addr), }
if let Some(want) = meta { let got = KnownLayout::pointer_to_metadata(slf.as_inner().as_ptr()); assert_eq!(got, want); } } }
if let Ok(slf) = Ptr::from_ref(bytes) .try_cast_into_no_leftover::<T, BecauseImmutable>(meta) { // SAFETY: All bytes in `bytes` have been // initialized. let len = unsafe { validate_and_get_len(slf) }; assert_eq!(len, bytes.len());
if let Some(want) = meta { let got = KnownLayout::pointer_to_metadata(slf.as_inner().as_ptr()); assert_eq!(got, want); } } } } } }
#[derive(FromBytes, KnownLayout, Immutable)] #[repr(C)] struct SliceDst<T> { a: u8, trailing: [T], }
// Each test case becomes its own `#[test]` function. We do this because // this test in particular takes far, far longer to execute under Miri // than all of our other tests combined. Previously, we had these // execute sequentially in a single test function. We run Miri tests in // parallel in CI, but this test being sequential meant that most of // that parallelism was wasted, as all other tests would finish in a // fraction of the total execution time, leaving this test to execute on // a single thread for the remainder of the test. By putting each test // case in its own function, we permit better use of available // parallelism. macro_rules! test { ($test_name:ident: $ty:ty) => { #[test] #[allow(non_snake_case)] fn $test_name() { const S: usize = core::mem::size_of::<$ty>(); const N: usize = if S == 0 { 4 } else { S * 4 }; test::<$ty, _, N>([None]);
// If `$ty` is a ZST, then we can't pass `None` as the // pointer metadata, or else computing the correct trailing // slice length will panic. if S == 0 { test::<[$ty], _, N>([Some(0), Some(1), Some(2), Some(3)]); test::<SliceDst<$ty>, _, N>([Some(0), Some(1), Some(2), Some(3)]); } else { test::<[$ty], _, N>([None, Some(0), Some(1), Some(2), Some(3)]); test::<SliceDst<$ty>, _, N>([None, Some(0), Some(1), Some(2), Some(3)]); } } }; ($ty:ident) => { test!($ty: $ty); }; ($($ty:ident),*) => { $(test!($ty);)* } }
test!(empty_tuple: ()); test!(u8, u16, u32, u64, usize, AU64); test!(i8, i16, i32, i64, isize); test!(f32, f64); }
#[test] fn test_try_cast_into_explicit_count() { macro_rules! test { ($ty:ty, $bytes:expr, $elems:expr, $expect:expr) => {{ let bytes = [0u8; $bytes]; let ptr = Ptr::from_ref(&bytes[..]); let res = ptr.try_cast_into::<$ty, BecauseImmutable>(CastType::Prefix, Some($elems)); if let Some(expect) = $expect { let (ptr, _) = res.unwrap(); assert_eq!(KnownLayout::pointer_to_metadata(ptr.as_inner().as_ptr()), expect); } else { let _ = res.unwrap_err(); } }}; }
#[derive(KnownLayout, Immutable)] #[repr(C)] struct ZstDst { u: [u8; 8], slc: [()], }
test!(ZstDst, 8, 0, Some(0)); test!(ZstDst, 7, 0, None);
test!(ZstDst, 8, usize::MAX, Some(usize::MAX)); test!(ZstDst, 7, usize::MAX, None);
#[derive(KnownLayout, Immutable)] #[repr(C)] struct Dst { u: [u8; 8], slc: [u8], }
test!(Dst, 8, 0, Some(0)); test!(Dst, 7, 0, None);
test!(Dst, 9, 1, Some(1)); test!(Dst, 8, 1, None);
// If we didn't properly check for overflow, this would cause the // metadata to overflow to 0, and thus the cast would spuriously // succeed. test!(Dst, 8, usize::MAX - 8 + 1, None); }
#[test] fn test_try_cast_into_no_leftover_restores_original_slice() { let bytes = [0u8; 4]; let ptr = Ptr::from_ref(&bytes[..]); let res = ptr.try_cast_into_no_leftover::<[u8; 2], BecauseImmutable>(None); match res { Ok(_) => panic!("should have failed due to leftover bytes"), Err(CastError::Size(e)) => { assert_eq!(e.into_src().len(), 4, "Should return original slice length"); } Err(e) => panic!("wrong error type: {:?}", e), } }
#[test] fn test_iter_exclusive_yields_disjoint_ptrs() { let mut arr = [0u8, 1, 2, 3];
{ let mut iter = Ptr::from_mut(&mut arr[..]).iter(); let first = iter.next().unwrap().as_mut(); let second = iter.next().unwrap().as_mut();
*first = 10; *second = 20; *first = 30; }
assert_eq!(arr, [30, 20, 2, 3]); }}