| 1 |
// Copyright 2023 The Fuchsia Authors |
| 2 |
// |
| 3 |
// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0 |
| 4 |
// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT |
| 5 |
// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option. |
| 6 |
// This file may not be copied, modified, or distributed except according to |
| 7 |
// those terms. |
| 8 |
|
| 9 |
use core::{ |
| 10 |
fmt::{Debug, Formatter}, |
| 11 |
marker::PhantomData, |
| 12 |
}; |
| 13 |
|
| 14 |
use crate::{ |
| 15 |
pointer::{ |
| 16 |
inner::PtrInner, |
| 17 |
invariant::*, |
| 18 |
transmute::{MutationCompatible, SizeEq, TransmuteFromPtr}, |
| 19 |
}, |
| 20 |
AlignmentError, CastError, CastType, KnownLayout, SizeError, TryFromBytes, ValidityError, |
| 21 |
}; |
| 22 |
|
| 23 |
/// Module used to gate access to [`Ptr`]'s fields. |
| 24 |
mod def { |
| 25 |
#[cfg(doc)] |
| 26 |
use super::super::invariant; |
| 27 |
use super::*; |
| 28 |
|
| 29 |
/// A raw pointer with more restrictions. |
| 30 |
/// |
| 31 |
/// `Ptr<T>` is similar to [`NonNull<T>`], but it is more restrictive in the |
| 32 |
/// following ways (note that these requirements only hold of non-zero-sized |
| 33 |
/// referents): |
| 34 |
/// - It must derive from a valid allocation. |
| 35 |
/// - It must reference a byte range which is contained inside the |
| 36 |
/// allocation from which it derives. |
| 37 |
/// - As a consequence, the byte range it references must have a size |
| 38 |
/// which does not overflow `isize`. |
| 39 |
/// |
| 40 |
/// Depending on how `Ptr` is parameterized, it may have additional |
| 41 |
/// invariants: |
| 42 |
/// - `ptr` conforms to the aliasing invariant of |
| 43 |
/// [`I::Aliasing`](invariant::Aliasing). |
| 44 |
/// - `ptr` conforms to the alignment invariant of |
| 45 |
/// [`I::Alignment`](invariant::Alignment). |
| 46 |
/// - `ptr` conforms to the validity invariant of |
| 47 |
/// [`I::Validity`](invariant::Validity). |
| 48 |
/// |
| 49 |
/// `Ptr<'a, T>` is [covariant] in `'a` and invariant in `T`. |
| 50 |
/// |
| 51 |
/// [`NonNull<T>`]: core::ptr::NonNull |
| 52 |
/// [covariant]: https://doc.rust-lang.org/reference/subtyping.html |
| 53 |
pub struct Ptr<'a, T, I> |
| 54 |
where |
| 55 |
T: ?Sized, |
| 56 |
I: Invariants, |
| 57 |
{ |
| 58 |
/// # Invariants |
| 59 |
/// |
| 60 |
/// 0. `ptr` conforms to the aliasing invariant of |
| 61 |
/// [`I::Aliasing`](invariant::Aliasing). |
| 62 |
/// 1. `ptr` conforms to the alignment invariant of |
| 63 |
/// [`I::Alignment`](invariant::Alignment). |
| 64 |
/// 2. `ptr` conforms to the validity invariant of |
| 65 |
/// [`I::Validity`](invariant::Validity). |
| 66 |
// SAFETY: `PtrInner<'a, T>` is covariant in `'a` and invariant in `T`. |
| 67 |
ptr: PtrInner<'a, T>, |
| 68 |
_invariants: PhantomData<I>, |
| 69 |
} |
| 70 |
|
| 71 |
impl<'a, T, I> Ptr<'a, T, I> |
| 72 |
where |
| 73 |
T: 'a + ?Sized, |
| 74 |
I: Invariants, |
| 75 |
{ |
| 76 |
/// Constructs a new `Ptr` from a [`PtrInner`]. |
| 77 |
/// |
| 78 |
/// # Safety |
| 79 |
/// |
| 80 |
/// The caller promises that: |
| 81 |
/// |
| 82 |
/// 0. `ptr` conforms to the aliasing invariant of |
| 83 |
/// [`I::Aliasing`](invariant::Aliasing). |
| 84 |
/// 1. `ptr` conforms to the alignment invariant of |
| 85 |
/// [`I::Alignment`](invariant::Alignment). |
| 86 |
/// 2. `ptr` conforms to the validity invariant of |
| 87 |
/// [`I::Validity`](invariant::Validity). |
| 88 |
pub(crate) unsafe fn from_inner(ptr: PtrInner<'a, T>) -> Ptr<'a, T, I> { |
| 89 |
// SAFETY: The caller has promised to satisfy all safety invariants |
| 90 |
// of `Ptr`. |
| 91 |
Self { ptr, _invariants: PhantomData } |
| 92 |
} |
| 93 |
|
| 94 |
/// Converts this `Ptr<T>` to a [`PtrInner<T>`]. |
| 95 |
/// |
| 96 |
/// Note that this method does not consume `self`. The caller should |
| 97 |
/// watch out for `unsafe` code which uses the returned value in a way |
| 98 |
/// that violates the safety invariants of `self`. |
| 99 |
pub(crate) fn as_inner(&self) -> PtrInner<'a, T> { |
| 100 |
self.ptr |
| 101 |
} |
| 102 |
} |
| 103 |
} |
| 104 |
|
| 105 |
#[allow(unreachable_pub)] // This is a false positive on our MSRV toolchain. |
| 106 |
pub use def::Ptr; |
| 107 |
|
| 108 |
/// External trait implementations on [`Ptr`]. |
| 109 |
mod _external { |
| 110 |
use super::*; |
| 111 |
|
| 112 |
/// SAFETY: Shared pointers are safely `Copy`. `Ptr`'s other invariants |
| 113 |
/// (besides aliasing) are unaffected by the number of references that exist |
| 114 |
/// to `Ptr`'s referent. The notable cases are: |
| 115 |
/// - Alignment is a property of the referent type (`T`) and the address, |
| 116 |
/// both of which are unchanged |
| 117 |
/// - Let `S(T, V)` be the set of bit values permitted to appear in the |
| 118 |
/// referent of a `Ptr<T, I: Invariants<Validity = V>>`. Since this copy |
| 119 |
/// does not change `I::Validity` or `T`, `S(T, I::Validity)` is also |
| 120 |
/// unchanged. |
| 121 |
/// |
| 122 |
/// We are required to guarantee that the referents of the original `Ptr` |
| 123 |
/// and of the copy (which, of course, are actually the same since they |
| 124 |
/// live in the same byte address range) both remain in the set `S(T, |
| 125 |
/// I::Validity)`. Since this invariant holds on the original `Ptr`, it |
| 126 |
/// cannot be violated by the original `Ptr`, and thus the original `Ptr` |
| 127 |
/// cannot be used to violate this invariant on the copy. The inverse |
| 128 |
/// holds as well. |
| 129 |
impl<'a, T, I> Copy for Ptr<'a, T, I> |
| 130 |
where |
| 131 |
T: 'a + ?Sized, |
| 132 |
I: Invariants<Aliasing = Shared>, |
| 133 |
{ |
| 134 |
} |
| 135 |
|
| 136 |
/// SAFETY: See the safety comment on `Copy`. |
| 137 |
impl<'a, T, I> Clone for Ptr<'a, T, I> |
| 138 |
where |
| 139 |
T: 'a + ?Sized, |
| 140 |
I: Invariants<Aliasing = Shared>, |
| 141 |
{ |
| 142 |
#[inline] |
| 143 |
fn clone(&self) -> Self { |
| 144 |
*self |
| 145 |
} |
| 146 |
} |
| 147 |
|
| 148 |
impl<'a, T, I> Debug for Ptr<'a, T, I> |
| 149 |
where |
| 150 |
T: 'a + ?Sized, |
| 151 |
I: Invariants, |
| 152 |
{ |
| 153 |
#[inline] |
| 154 |
fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result { |
| 155 |
self.as_inner().as_non_null().fmt(f) |
| 156 |
} |
| 157 |
} |
| 158 |
} |
| 159 |
|
| 160 |
/// Methods for converting to and from `Ptr` and Rust's safe reference types. |
| 161 |
mod _conversions { |
| 162 |
use super::*; |
| 163 |
|
| 164 |
/// `&'a T` → `Ptr<'a, T>` |
| 165 |
impl<'a, T> Ptr<'a, T, (Shared, Aligned, Valid)> |
| 166 |
where |
| 167 |
T: 'a + ?Sized, |
| 168 |
{ |
| 169 |
/// Constructs a `Ptr` from a shared reference. |
| 170 |
#[doc(hidden)] |
| 171 |
#[inline] |
| 172 |
pub fn from_ref(ptr: &'a T) -> Self { |
| 173 |
let inner = PtrInner::from_ref(ptr); |
| 174 |
// SAFETY: |
| 175 |
// 0. `ptr`, by invariant on `&'a T`, conforms to the aliasing |
| 176 |
// invariant of `Shared`. |
| 177 |
// 1. `ptr`, by invariant on `&'a T`, conforms to the alignment |
| 178 |
// invariant of `Aligned`. |
| 179 |
// 2. `ptr`'s referent, by invariant on `&'a T`, is a bit-valid `T`. |
| 180 |
// This satisfies the requirement that a `Ptr<T, (_, _, Valid)>` |
| 181 |
// point to a bit-valid `T`. Even if `T` permits interior |
| 182 |
// mutation, this invariant guarantees that the returned `Ptr` |
| 183 |
// can only ever be used to modify the referent to store |
| 184 |
// bit-valid `T`s, which ensures that the returned `Ptr` cannot |
| 185 |
// be used to violate the soundness of the original `ptr: &'a T` |
| 186 |
// or of any other references that may exist to the same |
| 187 |
// referent. |
| 188 |
unsafe { Self::from_inner(inner) } |
| 189 |
} |
| 190 |
} |
| 191 |
|
| 192 |
/// `&'a mut T` → `Ptr<'a, T>` |
| 193 |
impl<'a, T> Ptr<'a, T, (Exclusive, Aligned, Valid)> |
| 194 |
where |
| 195 |
T: 'a + ?Sized, |
| 196 |
{ |
| 197 |
/// Constructs a `Ptr` from an exclusive reference. |
| 198 |
#[inline] |
| 199 |
pub(crate) fn from_mut(ptr: &'a mut T) -> Self { |
| 200 |
let inner = PtrInner::from_mut(ptr); |
| 201 |
// SAFETY: |
| 202 |
// 0. `ptr`, by invariant on `&'a mut T`, conforms to the aliasing |
| 203 |
// invariant of `Exclusive`. |
| 204 |
// 1. `ptr`, by invariant on `&'a mut T`, conforms to the alignment |
| 205 |
// invariant of `Aligned`. |
| 206 |
// 2. `ptr`'s referent, by invariant on `&'a mut T`, is a bit-valid |
| 207 |
// `T`. This satisfies the requirement that a `Ptr<T, (_, _, |
| 208 |
// Valid)>` point to a bit-valid `T`. This invariant guarantees |
| 209 |
// that the returned `Ptr` can only ever be used to modify the |
| 210 |
// referent to store bit-valid `T`s, which ensures that the |
| 211 |
// returned `Ptr` cannot be used to violate the soundness of the |
| 212 |
// original `ptr: &'a mut T`. |
| 213 |
unsafe { Self::from_inner(inner) } |
| 214 |
} |
| 215 |
} |
| 216 |
|
| 217 |
/// `Ptr<'a, T>` → `&'a T` |
| 218 |
impl<'a, T, I> Ptr<'a, T, I> |
| 219 |
where |
| 220 |
T: 'a + ?Sized, |
| 221 |
I: Invariants<Alignment = Aligned, Validity = Valid>, |
| 222 |
I::Aliasing: Reference, |
| 223 |
{ |
| 224 |
/// Converts `self` to a shared reference. |
| 225 |
// This consumes `self`, not `&self`, because `self` is, logically, a |
| 226 |
// pointer. For `I::Aliasing = invariant::Shared`, `Self: Copy`, and so |
| 227 |
// this doesn't prevent the caller from still using the pointer after |
| 228 |
// calling `as_ref`. |
| 229 |
#[allow(clippy::wrong_self_convention)] |
| 230 |
pub(crate) fn as_ref(self) -> &'a T { |
| 231 |
let raw = self.as_inner().as_non_null(); |
| 232 |
// SAFETY: This invocation of `NonNull::as_ref` satisfies its |
| 233 |
// documented safety preconditions: |
| 234 |
// |
| 235 |
// 1. The pointer is properly aligned. This is ensured by-contract |
| 236 |
// on `Ptr`, because the `I::Alignment` is `Aligned`. |
| 237 |
// |
| 238 |
// 2. If the pointer's referent is not zero-sized, then the pointer |
| 239 |
// must be “dereferenceable” in the sense defined in the module |
| 240 |
// documentation; i.e.: |
| 241 |
// |
| 242 |
// > The memory range of the given size starting at the pointer |
| 243 |
// > must all be within the bounds of a single allocated object. |
| 244 |
// > [2] |
| 245 |
// |
| 246 |
// This is ensured by contract on all `PtrInner`s. |
| 247 |
// |
| 248 |
// 3. The pointer must point to a validly-initialized instance of |
| 249 |
// `T`. This is ensured by-contract on `Ptr`, because the |
| 250 |
// `I::Validity` is `Valid`. |
| 251 |
// |
| 252 |
// 4. You must enforce Rust’s aliasing rules. This is ensured by |
| 253 |
// contract on `Ptr`, because `I::Aliasing: Reference`. Either it |
| 254 |
// is `Shared` or `Exclusive`. If it is `Shared`, other |
| 255 |
// references may not mutate the referent outside of |
| 256 |
// `UnsafeCell`s. |
| 257 |
// |
| 258 |
// [1]: https://doc.rust-lang.org/std/ptr/struct.NonNull.html#method.as_ref |
| 259 |
// [2]: https://doc.rust-lang.org/std/ptr/index.html#safety |
| 260 |
unsafe { raw.as_ref() } |
| 261 |
} |
| 262 |
} |
| 263 |
|
| 264 |
impl<'a, T, I> Ptr<'a, T, I> |
| 265 |
where |
| 266 |
T: 'a + ?Sized, |
| 267 |
I: Invariants, |
| 268 |
I::Aliasing: Reference, |
| 269 |
{ |
| 270 |
/// Reborrows `self`, producing another `Ptr`. |
| 271 |
/// |
| 272 |
/// Since `self` is borrowed immutably, this prevents any mutable |
| 273 |
/// methods from being called on `self` as long as the returned `Ptr` |
| 274 |
/// exists. |
| 275 |
#[doc(hidden)] |
| 276 |
#[inline] |
| 277 |
#[allow(clippy::needless_lifetimes)] // Allows us to name the lifetime in the safety comment below. |
| 278 |
pub fn reborrow<'b>(&'b mut self) -> Ptr<'b, T, I> |
| 279 |
where |
| 280 |
'a: 'b, |
| 281 |
{ |
| 282 |
// SAFETY: The following all hold by invariant on `self`, and thus |
| 283 |
// hold of `ptr = self.as_inner()`: |
| 284 |
// 0. SEE BELOW. |
| 285 |
// 1. `ptr` conforms to the alignment invariant of |
| 286 |
// [`I::Alignment`](invariant::Alignment). |
| 287 |
// 2. `ptr` conforms to the validity invariant of |
| 288 |
// [`I::Validity`](invariant::Validity). `self` and the returned |
| 289 |
// `Ptr` permit the same bit values in their referents since they |
| 290 |
// have the same referent type (`T`) and the same validity |
| 291 |
// (`I::Validity`). Thus, regardless of what mutation is |
| 292 |
// permitted (`Exclusive` aliasing or `Shared`-aliased interior |
| 293 |
// mutation), neither can be used to write a value to the |
| 294 |
// referent which violates the other's validity invariant. |
| 295 |
// |
| 296 |
// For aliasing (0 above), since `I::Aliasing: Reference`, |
| 297 |
// there are two cases for `I::Aliasing`: |
| 298 |
// - For `invariant::Shared`: `'a` outlives `'b`, and so the |
| 299 |
// returned `Ptr` does not permit accessing the referent any |
| 300 |
// longer than is possible via `self`. For shared aliasing, it is |
| 301 |
// sound for multiple `Ptr`s to exist simultaneously which |
| 302 |
// reference the same memory, so creating a new one is not |
| 303 |
// problematic. |
| 304 |
// - For `invariant::Exclusive`: Since `self` is `&'b mut` and we |
| 305 |
// return a `Ptr` with lifetime `'b`, `self` is inaccessible to |
| 306 |
// the caller for the lifetime `'b` - in other words, `self` is |
| 307 |
// inaccessible to the caller as long as the returned `Ptr` |
| 308 |
// exists. Since `self` is an exclusive `Ptr`, no other live |
| 309 |
// references or `Ptr`s may exist which refer to the same memory |
| 310 |
// while `self` is live. Thus, as long as the returned `Ptr` |
| 311 |
// exists, no other references or `Ptr`s which refer to the same |
| 312 |
// memory may be live. |
| 313 |
unsafe { Ptr::from_inner(self.as_inner()) } |
| 314 |
} |
| 315 |
} |
| 316 |
|
| 317 |
/// `Ptr<'a, T>` → `&'a mut T` |
| 318 |
impl<'a, T> Ptr<'a, T, (Exclusive, Aligned, Valid)> |
| 319 |
where |
| 320 |
T: 'a + ?Sized, |
| 321 |
{ |
| 322 |
/// Converts `self` to a mutable reference. |
| 323 |
#[allow(clippy::wrong_self_convention)] |
| 324 |
pub(crate) fn as_mut(self) -> &'a mut T { |
| 325 |
let mut raw = self.as_inner().as_non_null(); |
| 326 |
// SAFETY: This invocation of `NonNull::as_mut` satisfies its |
| 327 |
// documented safety preconditions: |
| 328 |
// |
| 329 |
// 1. The pointer is properly aligned. This is ensured by-contract |
| 330 |
// on `Ptr`, because the `ALIGNMENT_INVARIANT` is `Aligned`. |
| 331 |
// |
| 332 |
// 2. If the pointer's referent is not zero-sized, then the pointer |
| 333 |
// must be “dereferenceable” in the sense defined in the module |
| 334 |
// documentation; i.e.: |
| 335 |
// |
| 336 |
// > The memory range of the given size starting at the pointer |
| 337 |
// > must all be within the bounds of a single allocated object. |
| 338 |
// > [2] |
| 339 |
// |
| 340 |
// This is ensured by contract on all `PtrInner`s. |
| 341 |
// |
| 342 |
// 3. The pointer must point to a validly-initialized instance of |
| 343 |
// `T`. This is ensured by-contract on `Ptr`, because the |
| 344 |
// validity invariant is `Valid`. |
| 345 |
// |
| 346 |
// 4. You must enforce Rust’s aliasing rules. This is ensured by |
| 347 |
// contract on `Ptr`, because the `ALIASING_INVARIANT` is |
| 348 |
// `Exclusive`. |
| 349 |
// |
| 350 |
// [1]: https://doc.rust-lang.org/std/ptr/struct.NonNull.html#method.as_mut |
| 351 |
// [2]: https://doc.rust-lang.org/std/ptr/index.html#safety |
| 352 |
unsafe { raw.as_mut() } |
| 353 |
} |
| 354 |
} |
| 355 |
|
| 356 |
/// `Ptr<'a, T>` → `Ptr<'a, U>` |
| 357 |
impl<'a, T: ?Sized, I> Ptr<'a, T, I> |
| 358 |
where |
| 359 |
I: Invariants, |
| 360 |
{ |
| 361 |
pub(crate) fn transmute<U, V, R>(self) -> Ptr<'a, U, (I::Aliasing, Unaligned, V)> |
| 362 |
where |
| 363 |
V: Validity, |
| 364 |
U: TransmuteFromPtr<T, I::Aliasing, I::Validity, V, R> + SizeEq<T> + ?Sized, |
| 365 |
{ |
| 366 |
// SAFETY: |
| 367 |
// - `SizeEq::cast_from_raw` promises to preserve address, |
| 368 |
// provenance, and the number of bytes in the referent |
| 369 |
// - If aliasing is `Shared`, then by `U: TransmuteFromPtr<T>`, at |
| 370 |
// least one of the following holds: |
| 371 |
// - `T: Immutable` and `U: Immutable`, in which case it is |
| 372 |
// trivially sound for shared code to operate on a `&T` and `&U` |
| 373 |
// at the same time, as neither can perform interior mutation |
| 374 |
// - It is directly guaranteed that it is sound for shared code to |
| 375 |
// operate on these references simultaneously |
| 376 |
// - By `U: TransmuteFromPtr<T, I::Aliasing, I::Validity, V>`, it is |
| 377 |
// sound to perform this transmute. |
| 378 |
unsafe { self.transmute_unchecked(SizeEq::cast_from_raw) } |
| 379 |
} |
| 380 |
|
| 381 |
#[doc(hidden)] |
| 382 |
#[inline(always)] |
| 383 |
#[must_use] |
| 384 |
pub fn recall_validity<V, R>(self) -> Ptr<'a, T, (I::Aliasing, I::Alignment, V)> |
| 385 |
where |
| 386 |
V: Validity, |
| 387 |
T: TransmuteFromPtr<T, I::Aliasing, I::Validity, V, R>, |
| 388 |
{ |
| 389 |
// SAFETY: |
| 390 |
// - This cast is a no-op, and so trivially preserves address, |
| 391 |
// referent size, and provenance |
| 392 |
// - It is trivially sound to have multiple `&T` referencing the same |
| 393 |
// referent simultaneously |
| 394 |
// - By `T: TransmuteFromPtr<T, I::Aliasing, I::Validity, V>`, it is |
| 395 |
// sound to perform this transmute. |
| 396 |
let ptr = unsafe { self.transmute_unchecked(SizeEq::cast_from_raw) }; |
| 397 |
// SAFETY: `self` and `ptr` have the same address and referent type. |
| 398 |
// Therefore, if `self` satisfies `I::Alignment`, then so does |
| 399 |
// `ptr`. |
| 400 |
unsafe { ptr.assume_alignment::<I::Alignment>() } |
| 401 |
} |
| 402 |
|
| 403 |
/// Casts to a different (unsized) target type without checking interior |
| 404 |
/// mutability. |
| 405 |
/// |
| 406 |
/// Callers should prefer [`cast_unsized`] where possible. |
| 407 |
/// |
| 408 |
/// [`cast_unsized`]: Ptr::cast_unsized |
| 409 |
/// |
| 410 |
/// # Safety |
| 411 |
/// |
| 412 |
/// The caller promises that `u = cast(p)` is a pointer cast with the |
| 413 |
/// following properties: |
| 414 |
/// - `u` addresses a subset of the bytes addressed by `p` |
| 415 |
/// - `u` has the same provenance as `p` |
| 416 |
/// - If `I::Aliasing` is [`Shared`], it must not be possible for safe |
| 417 |
/// code, operating on a `&T` and `&U` with the same referent |
| 418 |
/// simultaneously, to cause undefined behavior |
| 419 |
/// - It is sound to transmute a pointer of type `T` with aliasing |
| 420 |
/// `I::Aliasing` and validity `I::Validity` to a pointer of type `U` |
| 421 |
/// with aliasing `I::Aliasing` and validity `V`. This is a subtle |
| 422 |
/// soundness requirement that is a function of `T`, `U`, |
| 423 |
/// `I::Aliasing`, `I::Validity`, and `V`, and may depend upon the |
| 424 |
/// presence, absence, or specific location of `UnsafeCell`s in `T` |
| 425 |
/// and/or `U`. See [`Validity`] for more details. |
| 426 |
#[doc(hidden)] |
| 427 |
#[inline] |
| 428 |
pub unsafe fn transmute_unchecked<U: ?Sized, V, F>( |
| 429 |
self, |
| 430 |
cast: F, |
| 431 |
) -> Ptr<'a, U, (I::Aliasing, Unaligned, V)> |
| 432 |
where |
| 433 |
V: Validity, |
| 434 |
F: FnOnce(PtrInner<'a, T>) -> PtrInner<'a, U>, |
| 435 |
{ |
| 436 |
let ptr = cast(self.as_inner()); |
| 437 |
|
| 438 |
// SAFETY: |
| 439 |
// |
| 440 |
// The following safety arguments rely on the fact that the caller |
| 441 |
// promises that `cast` returns a `PtrInner` which addresses a |
| 442 |
// prefix of the bytes of `*self`, and so properties that hold of |
| 443 |
// `*self` also hold of `*ptr`. |
| 444 |
// |
| 445 |
// 0. `ptr` conforms to the aliasing invariant of `I::Aliasing`: |
| 446 |
// - `Exclusive`: `self` is the only `Ptr` or reference which is |
| 447 |
// permitted to read or modify the referent for the lifetime |
| 448 |
// `'a`. Since we consume `self` by value, the returned pointer |
| 449 |
// remains the only `Ptr` or reference which is permitted to |
| 450 |
// read or modify the referent for the lifetime `'a`. |
| 451 |
// - `Shared`: Since `self` has aliasing `Shared`, we know that |
| 452 |
// no other code may mutate the referent during the lifetime |
| 453 |
// `'a`, except via `UnsafeCell`s, and except as permitted by |
| 454 |
// `T`'s library safety invariants. The caller promises that |
| 455 |
// any safe operations which can be permitted on a `&T` and a |
| 456 |
// `&U` simultaneously must be sound. Thus, no operations on a |
| 457 |
// `&U` could violate `&T`'s library safety invariants, and |
| 458 |
// vice-versa. Since any mutation via shared references outside |
| 459 |
// of `UnsafeCell`s is unsound, this must be impossible using |
| 460 |
// `&T` and `&U`. |
| 461 |
// - `Inaccessible`: There are no restrictions we need to uphold. |
| 462 |
// 1. `ptr` trivially satisfies the alignment invariant `Unaligned`. |
| 463 |
// 2. The caller promises that `ptr` conforms to the validity |
| 464 |
// invariant `V` with respect to its referent type, `U`. |
| 465 |
unsafe { Ptr::from_inner(ptr) } |
| 466 |
} |
| 467 |
} |
| 468 |
|
| 469 |
/// `Ptr<'a, T, (_, _, _)>` → `Ptr<'a, Unalign<T>, (_, Aligned, _)>` |
| 470 |
impl<'a, T, I> Ptr<'a, T, I> |
| 471 |
where |
| 472 |
I: Invariants, |
| 473 |
{ |
| 474 |
/// Converts a `Ptr` an unaligned `T` into a `Ptr` to an aligned |
| 475 |
/// `Unalign<T>`. |
| 476 |
pub(crate) fn into_unalign( |
| 477 |
self, |
| 478 |
) -> Ptr<'a, crate::Unalign<T>, (I::Aliasing, Aligned, I::Validity)> { |
| 479 |
// SAFETY: |
| 480 |
// - This cast preserves provenance. |
| 481 |
// - This cast preserves address. `Unalign<T>` promises to have the |
| 482 |
// same size as `T`, and so the cast returns a pointer addressing |
| 483 |
// the same byte range as `p`. |
| 484 |
// - By the same argument, the returned pointer refers to |
| 485 |
// `UnsafeCell`s at the same locations as `p`. |
| 486 |
// - `Unalign<T>` promises to have the same bit validity as `T`. By |
| 487 |
// invariant on `Validity`, the set of bit patterns allowed in the |
| 488 |
// referent of a `Ptr<X, (_, _, V)>` is only a function of the |
| 489 |
// validity of `X` and of `V`. Thus, the set of bit patterns |
| 490 |
// allowed in the referent of a `Ptr<T, (_, _, I::Validity)>` is |
| 491 |
// the same as the set of bit patterns allowed in the referent of |
| 492 |
// a `Ptr<Unalign<T>, (_, _, I::Validity)>`. As a result, `self` |
| 493 |
// and the returned `Ptr` permit the same set of bit patterns in |
| 494 |
// their referents, and so neither can be used to violate the |
| 495 |
// validity of the other. |
| 496 |
let ptr = unsafe { self.transmute_unchecked(PtrInner::cast_sized) }; |
| 497 |
ptr.bikeshed_recall_aligned() |
| 498 |
} |
| 499 |
} |
| 500 |
|
| 501 |
impl<'a, T, I> Ptr<'a, T, I> |
| 502 |
where |
| 503 |
T: ?Sized, |
| 504 |
I: Invariants<Validity = Valid>, |
| 505 |
I::Aliasing: Reference, |
| 506 |
{ |
| 507 |
/// Reads the referent. |
| 508 |
#[must_use] |
| 509 |
#[inline] |
| 510 |
pub fn read_unaligned<R>(self) -> T |
| 511 |
where |
| 512 |
T: Copy, |
| 513 |
T: Read<I::Aliasing, R>, |
| 514 |
{ |
| 515 |
(*self.into_unalign().as_ref()).into_inner() |
| 516 |
} |
| 517 |
|
| 518 |
/// Views the value as an aligned reference. |
| 519 |
/// |
| 520 |
/// This is only available if `T` is [`Unaligned`]. |
| 521 |
#[must_use] |
| 522 |
#[inline] |
| 523 |
pub fn unaligned_as_ref(self) -> &'a T |
| 524 |
where |
| 525 |
T: crate::Unaligned, |
| 526 |
{ |
| 527 |
self.bikeshed_recall_aligned().as_ref() |
| 528 |
} |
| 529 |
} |
| 530 |
} |
| 531 |
|
| 532 |
/// State transitions between invariants. |
| 533 |
mod _transitions { |
| 534 |
use super::*; |
| 535 |
use crate::pointer::transmute::TryTransmuteFromPtr; |
| 536 |
|
| 537 |
impl<'a, T, I> Ptr<'a, T, I> |
| 538 |
where |
| 539 |
T: 'a + ?Sized, |
| 540 |
I: Invariants, |
| 541 |
{ |
| 542 |
/// Returns a `Ptr` with [`Exclusive`] aliasing if `self` already has |
| 543 |
/// `Exclusive` aliasing, or generates a compile-time assertion failure. |
| 544 |
/// |
| 545 |
/// This allows code which is generic over aliasing to down-cast to a |
| 546 |
/// concrete aliasing. |
| 547 |
/// |
| 548 |
/// [`Exclusive`]: crate::pointer::invariant::Exclusive |
| 549 |
#[inline] |
| 550 |
pub(crate) fn into_exclusive_or_pme( |
| 551 |
self, |
| 552 |
) -> Ptr<'a, T, (Exclusive, I::Alignment, I::Validity)> { |
| 553 |
// NOTE(https://github.com/rust-lang/rust/issues/131625): We do this |
| 554 |
// rather than just having `Aliasing::IS_EXCLUSIVE` have the panic |
| 555 |
// behavior because doing it that way causes rustdoc to fail while |
| 556 |
// attempting to document hidden items (since it evaluates the |
| 557 |
// constant - and thus panics). |
| 558 |
trait AliasingExt: Aliasing { |
| 559 |
const IS_EXCL: bool; |
| 560 |
} |
| 561 |
|
| 562 |
impl<A: Aliasing> AliasingExt for A { |
| 563 |
const IS_EXCL: bool = { |
| 564 |
const_assert!(Self::IS_EXCLUSIVE); |
| 565 |
true |
| 566 |
}; |
| 567 |
} |
| 568 |
|
| 569 |
assert!(I::Aliasing::IS_EXCL); |
| 570 |
|
| 571 |
// SAFETY: We've confirmed that `self` already has the aliasing |
| 572 |
// `Exclusive`. If it didn't, either the preceding assert would fail |
| 573 |
// or evaluating `I::Aliasing::IS_EXCL` would fail. We're *pretty* |
| 574 |
// sure that it's guaranteed to fail const eval, but the `assert!` |
| 575 |
// provides a backstop in case that doesn't work. |
| 576 |
unsafe { self.assume_exclusive() } |
| 577 |
} |
| 578 |
|
| 579 |
/// Assumes that `self` satisfies the invariants `H`. |
| 580 |
/// |
| 581 |
/// # Safety |
| 582 |
/// |
| 583 |
/// The caller promises that `self` satisfies the invariants `H`. |
| 584 |
unsafe fn assume_invariants<H: Invariants>(self) -> Ptr<'a, T, H> { |
| 585 |
// SAFETY: The caller has promised to satisfy all parameterized |
| 586 |
// invariants of `Ptr`. `Ptr`'s other invariants are satisfied |
| 587 |
// by-contract by the source `Ptr`. |
| 588 |
unsafe { Ptr::from_inner(self.as_inner()) } |
| 589 |
} |
| 590 |
|
| 591 |
/// Helps the type system unify two distinct invariant types which are |
| 592 |
/// actually the same. |
| 593 |
pub(crate) fn unify_invariants< |
| 594 |
H: Invariants<Aliasing = I::Aliasing, Alignment = I::Alignment, Validity = I::Validity>, |
| 595 |
>( |
| 596 |
self, |
| 597 |
) -> Ptr<'a, T, H> { |
| 598 |
// SAFETY: The associated type bounds on `H` ensure that the |
| 599 |
// invariants are unchanged. |
| 600 |
unsafe { self.assume_invariants::<H>() } |
| 601 |
} |
| 602 |
|
| 603 |
/// Assumes that `self` satisfies the aliasing requirement of `A`. |
| 604 |
/// |
| 605 |
/// # Safety |
| 606 |
/// |
| 607 |
/// The caller promises that `self` satisfies the aliasing requirement |
| 608 |
/// of `A`. |
| 609 |
#[inline] |
| 610 |
pub(crate) unsafe fn assume_aliasing<A: Aliasing>( |
| 611 |
self, |
| 612 |
) -> Ptr<'a, T, (A, I::Alignment, I::Validity)> { |
| 613 |
// SAFETY: The caller promises that `self` satisfies the aliasing |
| 614 |
// requirements of `A`. |
| 615 |
unsafe { self.assume_invariants() } |
| 616 |
} |
| 617 |
|
| 618 |
/// Assumes `self` satisfies the aliasing requirement of [`Exclusive`]. |
| 619 |
/// |
| 620 |
/// # Safety |
| 621 |
/// |
| 622 |
/// The caller promises that `self` satisfies the aliasing requirement |
| 623 |
/// of `Exclusive`. |
| 624 |
/// |
| 625 |
/// [`Exclusive`]: crate::pointer::invariant::Exclusive |
| 626 |
#[inline] |
| 627 |
pub(crate) unsafe fn assume_exclusive( |
| 628 |
self, |
| 629 |
) -> Ptr<'a, T, (Exclusive, I::Alignment, I::Validity)> { |
| 630 |
// SAFETY: The caller promises that `self` satisfies the aliasing |
| 631 |
// requirements of `Exclusive`. |
| 632 |
unsafe { self.assume_aliasing::<Exclusive>() } |
| 633 |
} |
| 634 |
|
| 635 |
/// Assumes that `self`'s referent is validly-aligned for `T` if |
| 636 |
/// required by `A`. |
| 637 |
/// |
| 638 |
/// # Safety |
| 639 |
/// |
| 640 |
/// The caller promises that `self`'s referent conforms to the alignment |
| 641 |
/// invariant of `T` if required by `A`. |
| 642 |
#[inline] |
| 643 |
pub(crate) unsafe fn assume_alignment<A: Alignment>( |
| 644 |
self, |
| 645 |
) -> Ptr<'a, T, (I::Aliasing, A, I::Validity)> { |
| 646 |
// SAFETY: The caller promises that `self`'s referent is |
| 647 |
// well-aligned for `T` if required by `A` . |
| 648 |
unsafe { self.assume_invariants() } |
| 649 |
} |
| 650 |
|
| 651 |
/// Checks the `self`'s alignment at runtime, returning an aligned `Ptr` |
| 652 |
/// on success. |
| 653 |
pub(crate) fn try_into_aligned( |
| 654 |
self, |
| 655 |
) -> Result<Ptr<'a, T, (I::Aliasing, Aligned, I::Validity)>, AlignmentError<Self, T>> |
| 656 |
where |
| 657 |
T: Sized, |
| 658 |
{ |
| 659 |
if let Err(err) = |
| 660 |
crate::util::validate_aligned_to::<_, T>(self.as_inner().as_non_null()) |
| 661 |
{ |
| 662 |
return Err(err.with_src(self)); |
| 663 |
} |
| 664 |
|
| 665 |
// SAFETY: We just checked the alignment. |
| 666 |
Ok(unsafe { self.assume_alignment::<Aligned>() }) |
| 667 |
} |
| 668 |
|
| 669 |
/// Recalls that `self`'s referent is validly-aligned for `T`. |
| 670 |
#[inline] |
| 671 |
// FIXME(#859): Reconsider the name of this method before making it |
| 672 |
// public. |
| 673 |
pub(crate) fn bikeshed_recall_aligned( |
| 674 |
self, |
| 675 |
) -> Ptr<'a, T, (I::Aliasing, Aligned, I::Validity)> |
| 676 |
where |
| 677 |
T: crate::Unaligned, |
| 678 |
{ |
| 679 |
// SAFETY: The bound `T: Unaligned` ensures that `T` has no |
| 680 |
// non-trivial alignment requirement. |
| 681 |
unsafe { self.assume_alignment::<Aligned>() } |
| 682 |
} |
| 683 |
|
| 684 |
/// Assumes that `self`'s referent conforms to the validity requirement |
| 685 |
/// of `V`. |
| 686 |
/// |
| 687 |
/// # Safety |
| 688 |
/// |
| 689 |
/// The caller promises that `self`'s referent conforms to the validity |
| 690 |
/// requirement of `V`. |
| 691 |
#[doc(hidden)] |
| 692 |
#[must_use] |
| 693 |
#[inline] |
| 694 |
pub unsafe fn assume_validity<V: Validity>( |
| 695 |
self, |
| 696 |
) -> Ptr<'a, T, (I::Aliasing, I::Alignment, V)> { |
| 697 |
// SAFETY: The caller promises that `self`'s referent conforms to |
| 698 |
// the validity requirement of `V`. |
| 699 |
unsafe { self.assume_invariants() } |
| 700 |
} |
| 701 |
|
| 702 |
/// A shorthand for `self.assume_validity<invariant::Initialized>()`. |
| 703 |
/// |
| 704 |
/// # Safety |
| 705 |
/// |
| 706 |
/// The caller promises to uphold the safety preconditions of |
| 707 |
/// `self.assume_validity<invariant::Initialized>()`. |
| 708 |
#[doc(hidden)] |
| 709 |
#[must_use] |
| 710 |
#[inline] |
| 711 |
pub unsafe fn assume_initialized( |
| 712 |
self, |
| 713 |
) -> Ptr<'a, T, (I::Aliasing, I::Alignment, Initialized)> { |
| 714 |
// SAFETY: The caller has promised to uphold the safety |
| 715 |
// preconditions. |
| 716 |
unsafe { self.assume_validity::<Initialized>() } |
| 717 |
} |
| 718 |
|
| 719 |
/// A shorthand for `self.assume_validity<Valid>()`. |
| 720 |
/// |
| 721 |
/// # Safety |
| 722 |
/// |
| 723 |
/// The caller promises to uphold the safety preconditions of |
| 724 |
/// `self.assume_validity<Valid>()`. |
| 725 |
#[doc(hidden)] |
| 726 |
#[must_use] |
| 727 |
#[inline] |
| 728 |
pub unsafe fn assume_valid(self) -> Ptr<'a, T, (I::Aliasing, I::Alignment, Valid)> { |
| 729 |
// SAFETY: The caller has promised to uphold the safety |
| 730 |
// preconditions. |
| 731 |
unsafe { self.assume_validity::<Valid>() } |
| 732 |
} |
| 733 |
|
| 734 |
/// Recalls that `self`'s referent is initialized. |
| 735 |
#[doc(hidden)] |
| 736 |
#[must_use] |
| 737 |
#[inline] |
| 738 |
// FIXME(#859): Reconsider the name of this method before making it |
| 739 |
// public. |
| 740 |
pub fn bikeshed_recall_initialized_from_bytes( |
| 741 |
self, |
| 742 |
) -> Ptr<'a, T, (I::Aliasing, I::Alignment, Initialized)> |
| 743 |
where |
| 744 |
T: crate::IntoBytes + crate::FromBytes, |
| 745 |
I: Invariants<Validity = Valid>, |
| 746 |
{ |
| 747 |
// SAFETY: The `T: IntoBytes + FromBytes` bound ensures that `T`'s |
| 748 |
// bit validity is equivalent to `[u8]`. In other words, the set of |
| 749 |
// allowed referents for a `Ptr<T, (_, _, Valid)>` is the set of |
| 750 |
// initialized bit patterns. The same is true of the set of allowed |
| 751 |
// referents for any `Ptr<_, (_, _, Initialized)>`. Thus, this call |
| 752 |
// does not change the set of allowed values in the referent. |
| 753 |
unsafe { self.assume_initialized() } |
| 754 |
} |
| 755 |
|
| 756 |
/// Recalls that `self`'s referent is initialized. |
| 757 |
#[doc(hidden)] |
| 758 |
#[must_use] |
| 759 |
#[inline] |
| 760 |
// FIXME(#859): Reconsider the name of this method before making it |
| 761 |
// public. |
| 762 |
pub fn bikeshed_recall_initialized_immutable( |
| 763 |
self, |
| 764 |
) -> Ptr<'a, T, (Shared, I::Alignment, Initialized)> |
| 765 |
where |
| 766 |
T: crate::IntoBytes + crate::Immutable, |
| 767 |
I: Invariants<Aliasing = Shared, Validity = Valid>, |
| 768 |
{ |
| 769 |
// SAFETY: Let `O` (for "old") be the set of allowed bit patterns in |
| 770 |
// `self`'s referent, and let `N` (for "new") be the set of allowed |
| 771 |
// bit patterns in the referent of the returned `Ptr`. `T: |
| 772 |
// IntoBytes` and `I: Invariants<Validity = Valid>` ensures that `O` |
| 773 |
// cannot contain any uninitialized bit patterns. Since the returned |
| 774 |
// `Ptr` has validity `Initialized`, `N` is equal to the set of all |
| 775 |
// initialized bit patterns. Thus, `O` is a subset of `N`, and so |
| 776 |
// the returned `Ptr`'s validity invariant is upheld. |
| 777 |
// |
| 778 |
// Since `T: Immutable` and aliasing is `Shared`, the returned `Ptr` |
| 779 |
// cannot be used to modify the referent. Before this call, `self`'s |
| 780 |
// referent is guaranteed by invariant on `Ptr` to satisfy `self`'s |
| 781 |
// validity invariant. Since the returned `Ptr` cannot be used to |
| 782 |
// modify the referent, this guarantee cannot be violated by the |
| 783 |
// returned `Ptr` (even if `O` is a strict subset of `N`). |
| 784 |
unsafe { self.assume_initialized() } |
| 785 |
} |
| 786 |
|
| 787 |
/// Checks that `self`'s referent is validly initialized for `T`, |
| 788 |
/// returning a `Ptr` with `Valid` on success. |
| 789 |
/// |
| 790 |
/// # Panics |
| 791 |
/// |
| 792 |
/// This method will panic if |
| 793 |
/// [`T::is_bit_valid`][TryFromBytes::is_bit_valid] panics. |
| 794 |
/// |
| 795 |
/// # Safety |
| 796 |
/// |
| 797 |
/// On error, unsafe code may rely on this method's returned |
| 798 |
/// `ValidityError` containing `self`. |
| 799 |
#[inline] |
| 800 |
pub(crate) fn try_into_valid<R, S>( |
| 801 |
mut self, |
| 802 |
) -> Result<Ptr<'a, T, (I::Aliasing, I::Alignment, Valid)>, ValidityError<Self, T>> |
| 803 |
where |
| 804 |
T: TryFromBytes |
| 805 |
+ Read<I::Aliasing, R> |
| 806 |
+ TryTransmuteFromPtr<T, I::Aliasing, I::Validity, Valid, S>, |
| 807 |
I::Aliasing: Reference, |
| 808 |
I: Invariants<Validity = Initialized>, |
| 809 |
{ |
| 810 |
// This call may panic. If that happens, it doesn't cause any soundness |
| 811 |
// issues, as we have not generated any invalid state which we need to |
| 812 |
// fix before returning. |
| 813 |
if T::is_bit_valid(self.reborrow().forget_aligned()) { |
| 814 |
// SAFETY: If `T::is_bit_valid`, code may assume that `self` |
| 815 |
// contains a bit-valid instance of `T`. By `T: |
| 816 |
// TryTransmuteFromPtr<T, I::Aliasing, I::Validity, Valid>`, so |
| 817 |
// long as `self`'s referent conforms to the `Valid` validity |
| 818 |
// for `T` (which we just confired), then this transmute is |
| 819 |
// sound. |
| 820 |
Ok(unsafe { self.assume_valid() }) |
| 821 |
} else { |
| 822 |
Err(ValidityError::new(self)) |
| 823 |
} |
| 824 |
} |
| 825 |
|
| 826 |
/// Forgets that `self`'s referent is validly-aligned for `T`. |
| 827 |
#[doc(hidden)] |
| 828 |
#[must_use] |
| 829 |
#[inline] |
| 830 |
pub fn forget_aligned(self) -> Ptr<'a, T, (I::Aliasing, Unaligned, I::Validity)> { |
| 831 |
// SAFETY: `Unaligned` is less restrictive than `Aligned`. |
| 832 |
unsafe { self.assume_invariants() } |
| 833 |
} |
| 834 |
} |
| 835 |
} |
| 836 |
|
| 837 |
/// Casts of the referent type. |
| 838 |
mod _casts { |
| 839 |
use super::*; |
| 840 |
|
| 841 |
impl<'a, T, I> Ptr<'a, T, I> |
| 842 |
where |
| 843 |
T: 'a + ?Sized, |
| 844 |
I: Invariants, |
| 845 |
{ |
| 846 |
/// Casts to a different (unsized) target type without checking interior |
| 847 |
/// mutability. |
| 848 |
/// |
| 849 |
/// Callers should prefer [`cast_unsized`] where possible. |
| 850 |
/// |
| 851 |
/// [`cast_unsized`]: Ptr::cast_unsized |
| 852 |
/// |
| 853 |
/// # Safety |
| 854 |
/// |
| 855 |
/// The caller promises that `u = cast(p)` is a pointer cast with the |
| 856 |
/// following properties: |
| 857 |
/// - `u` addresses a subset of the bytes addressed by `p` |
| 858 |
/// - `u` has the same provenance as `p` |
| 859 |
/// - If `I::Aliasing` is [`Shared`], it must not be possible for safe |
| 860 |
/// code, operating on a `&T` and `&U` with the same referent |
| 861 |
/// simultaneously, to cause undefined behavior |
| 862 |
/// |
| 863 |
/// `cast_unsized_unchecked` guarantees that the pointer passed to |
| 864 |
/// `cast` will reference a byte sequence which is either contained |
| 865 |
/// inside a single allocated object or is zero sized. In either case, |
| 866 |
/// this means that its size will fit in an `isize` and it will not wrap |
| 867 |
/// around the address space. |
| 868 |
#[doc(hidden)] |
| 869 |
#[inline] |
| 870 |
pub unsafe fn cast_unsized_unchecked<U, F: FnOnce(PtrInner<'a, T>) -> PtrInner<'a, U>>( |
| 871 |
self, |
| 872 |
cast: F, |
| 873 |
) -> Ptr<'a, U, (I::Aliasing, Unaligned, I::Validity)> |
| 874 |
where |
| 875 |
U: 'a + CastableFrom<T, I::Validity, I::Validity> + ?Sized, |
| 876 |
{ |
| 877 |
// SAFETY: |
| 878 |
// - The caller promises that `u = cast(p)` is a pointer which |
| 879 |
// satisfies: |
| 880 |
// - `u` addresses a subset of the bytes addressed by `p` |
| 881 |
// - `u` has the same provenance as `p` |
| 882 |
// - If `I::Aliasing` is [`Shared`], it must not be possible for |
| 883 |
// safe code, operating on a `&T` and `&U` with the same |
| 884 |
// referent simultaneously, to cause undefined behavior |
| 885 |
// - By `U: CastableFrom<T, I::Validity, I::Validity>`, |
| 886 |
// `I::Validity` is either `Uninit` or `Initialized`. In both |
| 887 |
// cases, the bit validity `I::Validity` has the same semantics |
| 888 |
// regardless of referent type. In other words, the set of allowed |
| 889 |
// referent values for `Ptr<T, (_, _, I::Validity)>` and `Ptr<U, |
| 890 |
// (_, _, I::Validity)>` are identical. As a consequence, neither |
| 891 |
// `self` nor the returned `Ptr` can be used to write values which |
| 892 |
// are invalid for the other. |
| 893 |
// |
| 894 |
// `transmute_unchecked` guarantees that it will only pass pointers |
| 895 |
// to `cast` which either reference a zero-sized byte range or |
| 896 |
// reference a byte range which is entirely contained inside of an |
| 897 |
// allocated object. |
| 898 |
unsafe { self.transmute_unchecked(cast) } |
| 899 |
} |
| 900 |
|
| 901 |
/// Casts to a different (unsized) target type. |
| 902 |
/// |
| 903 |
/// # Safety |
| 904 |
/// |
| 905 |
/// The caller promises that `u = cast(p)` is a pointer cast with the |
| 906 |
/// following properties: |
| 907 |
/// - `u` addresses a subset of the bytes addressed by `p` |
| 908 |
/// - `u` has the same provenance as `p` |
| 909 |
#[doc(hidden)] |
| 910 |
#[inline] |
| 911 |
pub unsafe fn cast_unsized<U, F, R>( |
| 912 |
self, |
| 913 |
cast: F, |
| 914 |
) -> Ptr<'a, U, (I::Aliasing, Unaligned, I::Validity)> |
| 915 |
where |
| 916 |
T: MutationCompatible<U, I::Aliasing, I::Validity, I::Validity, R>, |
| 917 |
U: 'a + ?Sized + CastableFrom<T, I::Validity, I::Validity>, |
| 918 |
F: FnOnce(PtrInner<'a, T>) -> PtrInner<'a, U>, |
| 919 |
{ |
| 920 |
// SAFETY: Because `T: MutationCompatible<U, I::Aliasing, R>`, one |
| 921 |
// of the following holds: |
| 922 |
// - `T: Read<I::Aliasing>` and `U: Read<I::Aliasing>`, in which |
| 923 |
// case one of the following holds: |
| 924 |
// - `I::Aliasing` is `Exclusive` |
| 925 |
// - `T` and `U` are both `Immutable` |
| 926 |
// - It is sound for safe code to operate on `&T` and `&U` with the |
| 927 |
// same referent simultaneously |
| 928 |
// |
| 929 |
// The caller promises all other safety preconditions. |
| 930 |
unsafe { self.cast_unsized_unchecked(cast) } |
| 931 |
} |
| 932 |
} |
| 933 |
|
| 934 |
impl<'a, T, I> Ptr<'a, T, I> |
| 935 |
where |
| 936 |
T: 'a + KnownLayout + ?Sized, |
| 937 |
I: Invariants<Validity = Initialized>, |
| 938 |
{ |
| 939 |
/// Casts this pointer-to-initialized into a pointer-to-bytes. |
| 940 |
#[allow(clippy::wrong_self_convention)] |
| 941 |
#[must_use] |
| 942 |
#[inline] |
| 943 |
pub fn as_bytes<R>(self) -> Ptr<'a, [u8], (I::Aliasing, Aligned, Valid)> |
| 944 |
where |
| 945 |
T: Read<I::Aliasing, R>, |
| 946 |
I::Aliasing: Reference, |
| 947 |
{ |
| 948 |
// SAFETY: `PtrInner::as_bytes` returns a pointer which addresses |
| 949 |
// the same byte range as its argument, and which has the same |
| 950 |
// provenance. |
| 951 |
let ptr = unsafe { self.cast_unsized(PtrInner::as_bytes) }; |
| 952 |
ptr.bikeshed_recall_aligned().recall_validity::<Valid, (_, (_, _))>() |
| 953 |
} |
| 954 |
} |
| 955 |
|
| 956 |
impl<'a, T, I, const N: usize> Ptr<'a, [T; N], I> |
| 957 |
where |
| 958 |
T: 'a, |
| 959 |
I: Invariants, |
| 960 |
{ |
| 961 |
/// Casts this pointer-to-array into a slice. |
| 962 |
#[allow(clippy::wrong_self_convention)] |
| 963 |
pub(crate) fn as_slice(self) -> Ptr<'a, [T], I> { |
| 964 |
let slice = self.as_inner().as_slice(); |
| 965 |
// SAFETY: Note that, by post-condition on `PtrInner::as_slice`, |
| 966 |
// `slice` refers to the same byte range as `self.as_inner()`. |
| 967 |
// |
| 968 |
// 0. Thus, `slice` conforms to the aliasing invariant of |
| 969 |
// `I::Aliasing` because `self` does. |
| 970 |
// 1. By the above lemma, `slice` conforms to the alignment |
| 971 |
// invariant of `I::Alignment` because `self` does. |
| 972 |
// 2. Since `[T; N]` and `[T]` have the same bit validity [1][2], |
| 973 |
// and since `self` and the returned `Ptr` have the same validity |
| 974 |
// invariant, neither `self` nor the returned `Ptr` can be used |
| 975 |
// to write a value to the referent which violates the other's |
| 976 |
// validity invariant. |
| 977 |
// |
| 978 |
// [1] Per https://doc.rust-lang.org/1.81.0/reference/type-layout.html#array-layout: |
| 979 |
// |
| 980 |
// An array of `[T; N]` has a size of `size_of::<T>() * N` and the |
| 981 |
// same alignment of `T`. Arrays are laid out so that the |
| 982 |
// zero-based `nth` element of the array is offset from the start |
| 983 |
// of the array by `n * size_of::<T>()` bytes. |
| 984 |
// |
| 985 |
// ... |
| 986 |
// |
| 987 |
// Slices have the same layout as the section of the array they |
| 988 |
// slice. |
| 989 |
// |
| 990 |
// [2] Per https://doc.rust-lang.org/1.81.0/reference/types/array.html#array-types: |
| 991 |
// |
| 992 |
// All elements of arrays are always initialized |
| 993 |
unsafe { Ptr::from_inner(slice) } |
| 994 |
} |
| 995 |
} |
| 996 |
|
| 997 |
/// For caller convenience, these methods are generic over alignment |
| 998 |
/// invariant. In practice, the referent is always well-aligned, because the |
| 999 |
/// alignment of `[u8]` is 1. |
| 1000 |
impl<'a, I> Ptr<'a, [u8], I> |
| 1001 |
where |
| 1002 |
I: Invariants<Validity = Valid>, |
| 1003 |
{ |
| 1004 |
/// Attempts to cast `self` to a `U` using the given cast type. |
| 1005 |
/// |
| 1006 |
/// If `U` is a slice DST and pointer metadata (`meta`) is provided, |
| 1007 |
/// then the cast will only succeed if it would produce an object with |
| 1008 |
/// the given metadata. |
| 1009 |
/// |
| 1010 |
/// Returns `None` if the resulting `U` would be invalidly-aligned, if |
| 1011 |
/// no `U` can fit in `self`, or if the provided pointer metadata |
| 1012 |
/// describes an invalid instance of `U`. On success, returns a pointer |
| 1013 |
/// to the largest-possible `U` which fits in `self`. |
| 1014 |
/// |
| 1015 |
/// # Safety |
| 1016 |
/// |
| 1017 |
/// The caller may assume that this implementation is correct, and may |
| 1018 |
/// rely on that assumption for the soundness of their code. In |
| 1019 |
/// particular, the caller may assume that, if `try_cast_into` returns |
| 1020 |
/// `Some((ptr, remainder))`, then `ptr` and `remainder` refer to |
| 1021 |
/// non-overlapping byte ranges within `self`, and that `ptr` and |
| 1022 |
/// `remainder` entirely cover `self`. Finally: |
| 1023 |
/// - If this is a prefix cast, `ptr` has the same address as `self`. |
| 1024 |
/// - If this is a suffix cast, `remainder` has the same address as |
| 1025 |
/// `self`. |
| 1026 |
#[inline(always)] |
| 1027 |
pub(crate) fn try_cast_into<U, R>( |
| 1028 |
self, |
| 1029 |
cast_type: CastType, |
| 1030 |
meta: Option<U::PointerMetadata>, |
| 1031 |
) -> Result< |
| 1032 |
(Ptr<'a, U, (I::Aliasing, Aligned, Initialized)>, Ptr<'a, [u8], I>), |
| 1033 |
CastError<Self, U>, |
| 1034 |
> |
| 1035 |
where |
| 1036 |
I::Aliasing: Reference, |
| 1037 |
U: 'a + ?Sized + KnownLayout + Read<I::Aliasing, R>, |
| 1038 |
{ |
| 1039 |
let (inner, remainder) = |
| 1040 |
self.as_inner().try_cast_into(cast_type, meta).map_err(|err| { |
| 1041 |
err.map_src(|inner| |
| 1042 |
// SAFETY: `PtrInner::try_cast_into` promises to return its |
| 1043 |
// original argument on error, which was originally produced |
| 1044 |
// by `self.as_inner()`, which is guaranteed to satisfy |
| 1045 |
// `Ptr`'s invariants. |
| 1046 |
unsafe { Ptr::from_inner(inner) }) |
| 1047 |
})?; |
| 1048 |
|
| 1049 |
// SAFETY: |
| 1050 |
// 0. Since `U: Read<I::Aliasing, _>`, either: |
| 1051 |
// - `I::Aliasing` is `Exclusive`, in which case both `src` and |
| 1052 |
// `ptr` conform to `Exclusive` |
| 1053 |
// - `I::Aliasing` is `Shared` and `U` is `Immutable` (we already |
| 1054 |
// know that `[u8]: Immutable`). In this case, neither `U` nor |
| 1055 |
// `[u8]` permit mutation, and so `Shared` aliasing is |
| 1056 |
// satisfied. |
| 1057 |
// 1. `ptr` conforms to the alignment invariant of `Aligned` because |
| 1058 |
// it is derived from `try_cast_into`, which promises that the |
| 1059 |
// object described by `target` is validly aligned for `U`. |
| 1060 |
// 2. By trait bound, `self` - and thus `target` - is a bit-valid |
| 1061 |
// `[u8]`. `Ptr<[u8], (_, _, Valid)>` and `Ptr<_, (_, _, |
| 1062 |
// Initialized)>` have the same bit validity, and so neither |
| 1063 |
// `self` nor `res` can be used to write a value to the referent |
| 1064 |
// which violates the other's validity invariant. |
| 1065 |
let res = unsafe { Ptr::from_inner(inner) }; |
| 1066 |
|
| 1067 |
// SAFETY: |
| 1068 |
// 0. `self` and `remainder` both have the type `[u8]`. Thus, they |
| 1069 |
// have `UnsafeCell`s at the same locations. Type casting does |
| 1070 |
// not affect aliasing. |
| 1071 |
// 1. `[u8]` has no alignment requirement. |
| 1072 |
// 2. `self` has validity `Valid` and has type `[u8]`. Since |
| 1073 |
// `remainder` references a subset of `self`'s referent, it is |
| 1074 |
// also a bit-valid `[u8]`. Thus, neither `self` nor `remainder` |
| 1075 |
// can be used to write a value to the referent which violates |
| 1076 |
// the other's validity invariant. |
| 1077 |
let remainder = unsafe { Ptr::from_inner(remainder) }; |
| 1078 |
|
| 1079 |
Ok((res, remainder)) |
| 1080 |
} |
| 1081 |
|
| 1082 |
/// Attempts to cast `self` into a `U`, failing if all of the bytes of |
| 1083 |
/// `self` cannot be treated as a `U`. |
| 1084 |
/// |
| 1085 |
/// In particular, this method fails if `self` is not validly-aligned |
| 1086 |
/// for `U` or if `self`'s size is not a valid size for `U`. |
| 1087 |
/// |
| 1088 |
/// # Safety |
| 1089 |
/// |
| 1090 |
/// On success, the caller may assume that the returned pointer |
| 1091 |
/// references the same byte range as `self`. |
| 1092 |
#[allow(unused)] |
| 1093 |
#[inline(always)] |
| 1094 |
pub(crate) fn try_cast_into_no_leftover<U, R>( |
| 1095 |
self, |
| 1096 |
meta: Option<U::PointerMetadata>, |
| 1097 |
) -> Result<Ptr<'a, U, (I::Aliasing, Aligned, Initialized)>, CastError<Self, U>> |
| 1098 |
where |
| 1099 |
I::Aliasing: Reference, |
| 1100 |
U: 'a + ?Sized + KnownLayout + Read<I::Aliasing, R>, |
| 1101 |
{ |
| 1102 |
// FIXME(#67): Remove this allow. See NonNulSlicelExt for more |
| 1103 |
// details. |
| 1104 |
#[allow(unstable_name_collisions)] |
| 1105 |
match self.try_cast_into(CastType::Prefix, meta) { |
| 1106 |
Ok((slf, remainder)) => { |
| 1107 |
if remainder.len() == 0 { |
| 1108 |
Ok(slf) |
| 1109 |
} else { |
| 1110 |
// Undo the cast so we can return the original bytes. |
| 1111 |
let slf = slf.as_bytes(); |
| 1112 |
// Restore the initial alignment invariant of `self`. |
| 1113 |
// |
| 1114 |
// SAFETY: The referent type of `slf` is now equal to |
| 1115 |
// that of `self`, but the alignment invariants |
| 1116 |
// nominally differ. Since `slf` and `self` refer to the |
| 1117 |
// same memory and no actions have been taken that would |
| 1118 |
// violate the original invariants on `self`, it is |
| 1119 |
// sound to apply the alignment invariant of `self` onto |
| 1120 |
// `slf`. |
| 1121 |
let slf = unsafe { slf.assume_alignment::<I::Alignment>() }; |
| 1122 |
let slf = slf.unify_invariants(); |
| 1123 |
Err(CastError::Size(SizeError::<_, U>::new(slf))) |
| 1124 |
} |
| 1125 |
} |
| 1126 |
Err(err) => Err(err), |
| 1127 |
} |
| 1128 |
} |
| 1129 |
} |
| 1130 |
|
| 1131 |
impl<'a, T, I> Ptr<'a, core::cell::UnsafeCell<T>, I> |
| 1132 |
where |
| 1133 |
T: 'a + ?Sized, |
| 1134 |
I: Invariants<Aliasing = Exclusive>, |
| 1135 |
{ |
| 1136 |
/// Converts this `Ptr` into a pointer to the underlying data. |
| 1137 |
/// |
| 1138 |
/// This call borrows the `UnsafeCell` mutably (at compile-time) which |
| 1139 |
/// guarantees that we possess the only reference. |
| 1140 |
/// |
| 1141 |
/// This is like [`UnsafeCell::get_mut`], but for `Ptr`. |
| 1142 |
/// |
| 1143 |
/// [`UnsafeCell::get_mut`]: core::cell::UnsafeCell::get_mut |
| 1144 |
#[must_use] |
| 1145 |
#[inline(always)] |
| 1146 |
pub fn get_mut(self) -> Ptr<'a, T, I> { |
| 1147 |
// SAFETY: |
| 1148 |
// - The closure uses an `as` cast, which preserves address range |
| 1149 |
// and provenance. |
| 1150 |
// - Aliasing is `Exclusive`, and so we are not required to promise |
| 1151 |
// anything about the locations of `UnsafeCell`s. |
| 1152 |
// - `UnsafeCell<T>` has the same bit validity as `T` [1]. |
| 1153 |
// Technically the term "representation" doesn't guarantee this, |
| 1154 |
// but the subsequent sentence in the documentation makes it clear |
| 1155 |
// that this is the intention. |
| 1156 |
// |
| 1157 |
// By invariant on `Validity`, since `T` and `UnsafeCell<T>` have |
| 1158 |
// the same bit validity, then the set of values which may appear |
| 1159 |
// in the referent of a `Ptr<T, (_, _, V)>` is the same as the set |
| 1160 |
// which may appear in the referent of a `Ptr<UnsafeCell<T>, (_, |
| 1161 |
// _, V)>`. Thus, neither `self` nor `ptr` may be used to write a |
| 1162 |
// value to the referent which would violate the other's validity |
| 1163 |
// invariant. |
| 1164 |
// |
| 1165 |
// [1] Per https://doc.rust-lang.org/1.81.0/core/cell/struct.UnsafeCell.html#memory-layout: |
| 1166 |
// |
| 1167 |
// `UnsafeCell<T>` has the same in-memory representation as its |
| 1168 |
// inner type `T`. A consequence of this guarantee is that it is |
| 1169 |
// possible to convert between `T` and `UnsafeCell<T>`. |
| 1170 |
#[allow(clippy::as_conversions)] |
| 1171 |
let ptr = unsafe { self.transmute_unchecked(|ptr| cast!(ptr)) }; |
| 1172 |
|
| 1173 |
// SAFETY: `UnsafeCell<T>` has the same alignment as `T` [1], |
| 1174 |
// and so if `self` is guaranteed to be aligned, then so is the |
| 1175 |
// returned `Ptr`. |
| 1176 |
// |
| 1177 |
// [1] Per https://doc.rust-lang.org/1.81.0/core/cell/struct.UnsafeCell.html#memory-layout: |
| 1178 |
// |
| 1179 |
// `UnsafeCell<T>` has the same in-memory representation as |
| 1180 |
// its inner type `T`. A consequence of this guarantee is that |
| 1181 |
// it is possible to convert between `T` and `UnsafeCell<T>`. |
| 1182 |
let ptr = unsafe { ptr.assume_alignment::<I::Alignment>() }; |
| 1183 |
ptr.unify_invariants() |
| 1184 |
} |
| 1185 |
} |
| 1186 |
} |
| 1187 |
|
| 1188 |
/// Projections through the referent. |
| 1189 |
mod _project { |
| 1190 |
use super::*; |
| 1191 |
|
| 1192 |
impl<'a, T, I> Ptr<'a, [T], I> |
| 1193 |
where |
| 1194 |
T: 'a, |
| 1195 |
I: Invariants, |
| 1196 |
I::Aliasing: Reference, |
| 1197 |
{ |
| 1198 |
/// Iteratively projects the elements `Ptr<T>` from `Ptr<[T]>`. |
| 1199 |
pub(crate) fn iter(&self) -> impl Iterator<Item = Ptr<'a, T, I>> { |
| 1200 |
// SAFETY: |
| 1201 |
// 0. `elem` conforms to the aliasing invariant of `I::Aliasing` |
| 1202 |
// because projection does not impact the aliasing invariant. |
| 1203 |
// 1. `elem`, conditionally, conforms to the validity invariant of |
| 1204 |
// `I::Alignment`. If `elem` is projected from data well-aligned |
| 1205 |
// for `[T]`, `elem` will be valid for `T`. |
| 1206 |
// 2. FIXME: Need to cite facts about `[T]`'s layout (same for the |
| 1207 |
// preceding points) |
| 1208 |
self.as_inner().iter().map(|elem| unsafe { Ptr::from_inner(elem) }) |
| 1209 |
} |
| 1210 |
} |
| 1211 |
|
| 1212 |
#[allow(clippy::needless_lifetimes)] |
| 1213 |
impl<'a, T, I> Ptr<'a, T, I> |
| 1214 |
where |
| 1215 |
T: 'a + ?Sized + KnownLayout<PointerMetadata = usize>, |
| 1216 |
I: Invariants, |
| 1217 |
{ |
| 1218 |
/// The number of slice elements in the object referenced by `self`. |
| 1219 |
pub(crate) fn len(&self) -> usize { |
| 1220 |
self.as_inner().meta().get() |
| 1221 |
} |
| 1222 |
} |
| 1223 |
} |
| 1224 |
|
| 1225 |
#[cfg(test)] |
| 1226 |
mod tests { |
| 1227 |
use core::mem::{self, MaybeUninit}; |
| 1228 |
|
| 1229 |
use super::*; |
| 1230 |
#[allow(unused)] // Needed on our MSRV, but considered unused on later toolchains. |
| 1231 |
use crate::util::AsAddress; |
| 1232 |
use crate::{pointer::BecauseImmutable, util::testutil::AU64, FromBytes, Immutable}; |
| 1233 |
|
| 1234 |
mod test_ptr_try_cast_into_soundness { |
| 1235 |
use super::*; |
| 1236 |
|
| 1237 |
// This test is designed so that if `Ptr::try_cast_into_xxx` are |
| 1238 |
// buggy, it will manifest as unsoundness that Miri can detect. |
| 1239 |
|
| 1240 |
// - If `size_of::<T>() == 0`, `N == 4` |
| 1241 |
// - Else, `N == 4 * size_of::<T>()` |
| 1242 |
// |
| 1243 |
// Each test will be run for each metadata in `metas`. |
| 1244 |
fn test<T, I, const N: usize>(metas: I) |
| 1245 |
where |
| 1246 |
T: ?Sized + KnownLayout + Immutable + FromBytes, |
| 1247 |
I: IntoIterator<Item = Option<T::PointerMetadata>> + Clone, |
| 1248 |
{ |
| 1249 |
let mut bytes = [MaybeUninit::<u8>::uninit(); N]; |
| 1250 |
let initialized = [MaybeUninit::new(0u8); N]; |
| 1251 |
for start in 0..=bytes.len() { |
| 1252 |
for end in start..=bytes.len() { |
| 1253 |
// Set all bytes to uninitialized other than those in |
| 1254 |
// the range we're going to pass to `try_cast_from`. |
| 1255 |
// This allows Miri to detect out-of-bounds reads |
| 1256 |
// because they read uninitialized memory. Without this, |
| 1257 |
// some out-of-bounds reads would still be in-bounds of |
| 1258 |
// `bytes`, and so might spuriously be accepted. |
| 1259 |
bytes = [MaybeUninit::<u8>::uninit(); N]; |
| 1260 |
let bytes = &mut bytes[start..end]; |
| 1261 |
// Initialize only the byte range we're going to pass to |
| 1262 |
// `try_cast_from`. |
| 1263 |
bytes.copy_from_slice(&initialized[start..end]); |
| 1264 |
|
| 1265 |
let bytes = { |
| 1266 |
let bytes: *const [MaybeUninit<u8>] = bytes; |
| 1267 |
#[allow(clippy::as_conversions)] |
| 1268 |
let bytes = bytes as *const [u8]; |
| 1269 |
// SAFETY: We just initialized these bytes to valid |
| 1270 |
// `u8`s. |
| 1271 |
unsafe { &*bytes } |
| 1272 |
}; |
| 1273 |
|
| 1274 |
// SAFETY: The bytes in `slf` must be initialized. |
| 1275 |
unsafe fn validate_and_get_len< |
| 1276 |
T: ?Sized + KnownLayout + FromBytes + Immutable, |
| 1277 |
>( |
| 1278 |
slf: Ptr<'_, T, (Shared, Aligned, Initialized)>, |
| 1279 |
) -> usize { |
| 1280 |
let t = slf.recall_validity().as_ref(); |
| 1281 |
|
| 1282 |
let bytes = { |
| 1283 |
let len = mem::size_of_val(t); |
| 1284 |
let t: *const T = t; |
| 1285 |
// SAFETY: |
| 1286 |
// - We know `t`'s bytes are all initialized |
| 1287 |
// because we just read it from `slf`, which |
| 1288 |
// points to an initialized range of bytes. If |
| 1289 |
// there's a bug and this doesn't hold, then |
| 1290 |
// that's exactly what we're hoping Miri will |
| 1291 |
// catch! |
| 1292 |
// - Since `T: FromBytes`, `T` doesn't contain |
| 1293 |
// any `UnsafeCell`s, so it's okay for `t: T` |
| 1294 |
// and a `&[u8]` to the same memory to be |
| 1295 |
// alive concurrently. |
| 1296 |
unsafe { core::slice::from_raw_parts(t.cast::<u8>(), len) } |
| 1297 |
}; |
| 1298 |
|
| 1299 |
// This assertion ensures that `t`'s bytes are read |
| 1300 |
// and compared to another value, which in turn |
| 1301 |
// ensures that Miri gets a chance to notice if any |
| 1302 |
// of `t`'s bytes are uninitialized, which they |
| 1303 |
// shouldn't be (see the comment above). |
| 1304 |
assert_eq!(bytes, vec![0u8; bytes.len()]); |
| 1305 |
|
| 1306 |
mem::size_of_val(t) |
| 1307 |
} |
| 1308 |
|
| 1309 |
for meta in metas.clone().into_iter() { |
| 1310 |
for cast_type in [CastType::Prefix, CastType::Suffix] { |
| 1311 |
if let Ok((slf, remaining)) = Ptr::from_ref(bytes) |
| 1312 |
.try_cast_into::<T, BecauseImmutable>(cast_type, meta) |
| 1313 |
{ |
| 1314 |
// SAFETY: All bytes in `bytes` have been |
| 1315 |
// initialized. |
| 1316 |
let len = unsafe { validate_and_get_len(slf) }; |
| 1317 |
assert_eq!(remaining.len(), bytes.len() - len); |
| 1318 |
#[allow(unstable_name_collisions)] |
| 1319 |
let bytes_addr = bytes.as_ptr().addr(); |
| 1320 |
#[allow(unstable_name_collisions)] |
| 1321 |
let remaining_addr = |
| 1322 |
remaining.as_inner().as_non_null().as_ptr().addr(); |
| 1323 |
match cast_type { |
| 1324 |
CastType::Prefix => { |
| 1325 |
assert_eq!(remaining_addr, bytes_addr + len) |
| 1326 |
} |
| 1327 |
CastType::Suffix => assert_eq!(remaining_addr, bytes_addr), |
| 1328 |
} |
| 1329 |
|
| 1330 |
if let Some(want) = meta { |
| 1331 |
let got = KnownLayout::pointer_to_metadata( |
| 1332 |
slf.as_inner().as_non_null().as_ptr(), |
| 1333 |
); |
| 1334 |
assert_eq!(got, want); |
| 1335 |
} |
| 1336 |
} |
| 1337 |
} |
| 1338 |
|
| 1339 |
if let Ok(slf) = Ptr::from_ref(bytes) |
| 1340 |
.try_cast_into_no_leftover::<T, BecauseImmutable>(meta) |
| 1341 |
{ |
| 1342 |
// SAFETY: All bytes in `bytes` have been |
| 1343 |
// initialized. |
| 1344 |
let len = unsafe { validate_and_get_len(slf) }; |
| 1345 |
assert_eq!(len, bytes.len()); |
| 1346 |
|
| 1347 |
if let Some(want) = meta { |
| 1348 |
let got = KnownLayout::pointer_to_metadata( |
| 1349 |
slf.as_inner().as_non_null().as_ptr(), |
| 1350 |
); |
| 1351 |
assert_eq!(got, want); |
| 1352 |
} |
| 1353 |
} |
| 1354 |
} |
| 1355 |
} |
| 1356 |
} |
| 1357 |
} |
| 1358 |
|
| 1359 |
#[derive(FromBytes, KnownLayout, Immutable)] |
| 1360 |
#[repr(C)] |
| 1361 |
struct SliceDst<T> { |
| 1362 |
a: u8, |
| 1363 |
trailing: [T], |
| 1364 |
} |
| 1365 |
|
| 1366 |
// Each test case becomes its own `#[test]` function. We do this because |
| 1367 |
// this test in particular takes far, far longer to execute under Miri |
| 1368 |
// than all of our other tests combined. Previously, we had these |
| 1369 |
// execute sequentially in a single test function. We run Miri tests in |
| 1370 |
// parallel in CI, but this test being sequential meant that most of |
| 1371 |
// that parallelism was wasted, as all other tests would finish in a |
| 1372 |
// fraction of the total execution time, leaving this test to execute on |
| 1373 |
// a single thread for the remainder of the test. By putting each test |
| 1374 |
// case in its own function, we permit better use of available |
| 1375 |
// parallelism. |
| 1376 |
macro_rules! test { |
| 1377 |
($test_name:ident: $ty:ty) => { |
| 1378 |
#[test] |
| 1379 |
#[allow(non_snake_case)] |
| 1380 |
fn $test_name() { |
| 1381 |
const S: usize = core::mem::size_of::<$ty>(); |
| 1382 |
const N: usize = if S == 0 { 4 } else { S * 4 }; |
| 1383 |
test::<$ty, _, N>([None]); |
| 1384 |
|
| 1385 |
// If `$ty` is a ZST, then we can't pass `None` as the |
| 1386 |
// pointer metadata, or else computing the correct trailing |
| 1387 |
// slice length will panic. |
| 1388 |
if S == 0 { |
| 1389 |
test::<[$ty], _, N>([Some(0), Some(1), Some(2), Some(3)]); |
| 1390 |
test::<SliceDst<$ty>, _, N>([Some(0), Some(1), Some(2), Some(3)]); |
| 1391 |
} else { |
| 1392 |
test::<[$ty], _, N>([None, Some(0), Some(1), Some(2), Some(3)]); |
| 1393 |
test::<SliceDst<$ty>, _, N>([None, Some(0), Some(1), Some(2), Some(3)]); |
| 1394 |
} |
| 1395 |
} |
| 1396 |
}; |
| 1397 |
($ty:ident) => { |
| 1398 |
test!($ty: $ty); |
| 1399 |
}; |
| 1400 |
($($ty:ident),*) => { $(test!($ty);)* } |
| 1401 |
} |
| 1402 |
|
| 1403 |
test!(empty_tuple: ()); |
| 1404 |
test!(u8, u16, u32, u64, u128, usize, AU64); |
| 1405 |
test!(i8, i16, i32, i64, i128, isize); |
| 1406 |
test!(f32, f64); |
| 1407 |
} |
| 1408 |
|
| 1409 |
#[test] |
| 1410 |
fn test_try_cast_into_explicit_count() { |
| 1411 |
macro_rules! test { |
| 1412 |
($ty:ty, $bytes:expr, $elems:expr, $expect:expr) => {{ |
| 1413 |
let bytes = [0u8; $bytes]; |
| 1414 |
let ptr = Ptr::from_ref(&bytes[..]); |
| 1415 |
let res = |
| 1416 |
ptr.try_cast_into::<$ty, BecauseImmutable>(CastType::Prefix, Some($elems)); |
| 1417 |
if let Some(expect) = $expect { |
| 1418 |
let (ptr, _) = res.unwrap(); |
| 1419 |
assert_eq!( |
| 1420 |
KnownLayout::pointer_to_metadata(ptr.as_inner().as_non_null().as_ptr()), |
| 1421 |
expect |
| 1422 |
); |
| 1423 |
} else { |
| 1424 |
let _ = res.unwrap_err(); |
| 1425 |
} |
| 1426 |
}}; |
| 1427 |
} |
| 1428 |
|
| 1429 |
#[derive(KnownLayout, Immutable)] |
| 1430 |
#[repr(C)] |
| 1431 |
struct ZstDst { |
| 1432 |
u: [u8; 8], |
| 1433 |
slc: [()], |
| 1434 |
} |
| 1435 |
|
| 1436 |
test!(ZstDst, 8, 0, Some(0)); |
| 1437 |
test!(ZstDst, 7, 0, None); |
| 1438 |
|
| 1439 |
test!(ZstDst, 8, usize::MAX, Some(usize::MAX)); |
| 1440 |
test!(ZstDst, 7, usize::MAX, None); |
| 1441 |
|
| 1442 |
#[derive(KnownLayout, Immutable)] |
| 1443 |
#[repr(C)] |
| 1444 |
struct Dst { |
| 1445 |
u: [u8; 8], |
| 1446 |
slc: [u8], |
| 1447 |
} |
| 1448 |
|
| 1449 |
test!(Dst, 8, 0, Some(0)); |
| 1450 |
test!(Dst, 7, 0, None); |
| 1451 |
|
| 1452 |
test!(Dst, 9, 1, Some(1)); |
| 1453 |
test!(Dst, 8, 1, None); |
| 1454 |
|
| 1455 |
// If we didn't properly check for overflow, this would cause the |
| 1456 |
// metadata to overflow to 0, and thus the cast would spuriously |
| 1457 |
// succeed. |
| 1458 |
test!(Dst, 8, usize::MAX - 8 + 1, None); |
| 1459 |
} |
| 1460 |
} |