zerocopy/pointer/
mod.rs

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//! Abstractions over raw pointers.
10
11mod inner;
12#[doc(hidden)]
13pub mod invariant;
14mod ptr;
15
16#[doc(hidden)]
17pub use invariant::{BecauseExclusive, BecauseImmutable, Read, ReadReason};
18#[doc(hidden)]
19pub use ptr::Ptr;
20
21use crate::Unaligned;
22
23/// A shorthand for a maybe-valid, maybe-aligned reference. Used as the argument
24/// to [`TryFromBytes::is_bit_valid`].
25///
26/// [`TryFromBytes::is_bit_valid`]: crate::TryFromBytes::is_bit_valid
27pub type Maybe<'a, T, Aliasing = invariant::Shared, Alignment = invariant::Unaligned> =
28    Ptr<'a, T, (Aliasing, Alignment, invariant::Initialized)>;
29
30/// A semi-user-facing wrapper type representing a maybe-aligned reference, for
31/// use in [`TryFromBytes::is_bit_valid`].
32///
33/// [`TryFromBytes::is_bit_valid`]: crate::TryFromBytes::is_bit_valid
34pub type MaybeAligned<'a, T, Aliasing = invariant::Shared, Alignment = invariant::Unaligned> =
35    Ptr<'a, T, (Aliasing, Alignment, invariant::Valid)>;
36
37// These methods are defined on the type alias, `MaybeAligned`, so as to bring
38// them to the forefront of the rendered rustdoc for that type alias.
39impl<'a, T, Aliasing, Alignment> MaybeAligned<'a, T, Aliasing, Alignment>
40where
41    T: 'a + ?Sized,
42    Aliasing: invariant::Aliasing,
43    Alignment: invariant::Alignment,
44{
45    /// Reads the value from `MaybeAligned`.
46    #[must_use]
47    #[inline]
48    pub fn read_unaligned<R>(self) -> T
49    where
50        T: Copy,
51        R: invariant::ReadReason,
52        T: invariant::Read<Aliasing, R>,
53    {
54        // SAFETY: By invariant on `MaybeAligned`, `raw` contains
55        // validly-initialized data for `T`. By `T: Read<Aliasing>`, we are
56        // permitted to perform a read of `self`'s referent.
57        unsafe { self.as_inner().read_unaligned() }
58    }
59}
60
61impl<'a, T, Aliasing, Alignment> MaybeAligned<'a, T, Aliasing, Alignment>
62where
63    T: 'a + ?Sized,
64    Aliasing: invariant::Reference,
65    Alignment: invariant::Alignment,
66{
67    /// Views the value as an aligned reference.
68    ///
69    /// This is only available if `T` is [`Unaligned`].
70    #[must_use]
71    #[inline]
72    pub fn unaligned_as_ref(self) -> &'a T
73    where
74        T: Unaligned,
75    {
76        self.bikeshed_recall_aligned().as_ref()
77    }
78}
79
80/// Checks if the referent is zeroed.
81pub(crate) fn is_zeroed<T, I>(ptr: Ptr<'_, T, I>) -> bool
82where
83    T: crate::Immutable + crate::KnownLayout,
84    I: invariant::Invariants<Validity = invariant::Initialized>,
85    I::Aliasing: invariant::Reference,
86{
87    ptr.as_bytes::<BecauseImmutable>().as_ref().iter().all(|&byte| byte == 0)
88}
zerocopy/pointer/mod.rs

zerocopy/pointer/
mod.rs
