kernel/types/
for_lt.rs

1// SPDX-License-Identifier: Apache-2.0 OR MIT
2
3//! Provide implementation and test of the [`trait@ForLt`] and [`trait@CovariantForLt`] traits and
4//! macros.
5//!
6//! This module is hidden and users should just use [`ForLt!`](macro@ForLt) /
7//! [`CovariantForLt!`](macro@CovariantForLt) directly.
8
9use core::marker::PhantomData;
10
11/// Representation of types generic over a lifetime.
12///
13/// # Macro
14///
15/// It is not recommended to implement this trait directly. [`ForLt!`](macro@ForLt) macro is
16/// provided to obtain a type that implements this trait.
17///
18/// The full syntax is
19///
20/// ```
21/// # use kernel::types::ForLt;
22/// # fn expect_lt<F: ForLt>() {}
23/// # struct TypeThatUse<'a>(&'a ());
24/// # expect_lt::<
25/// ForLt!(for<'a> TypeThatUse<'a>)
26/// # >();
27/// ```
28///
29/// which gives a type so that `<ForLt!(for<'a> TypeThatUse<'a>) as ForLt>::Of<'b>`
30/// is `TypeThatUse<'b>`.
31///
32/// You may also use a short-hand syntax which works similar to lifetime elision.
33/// The macro also accepts types that do not involve a lifetime at all.
34///
35/// ```
36/// # use kernel::types::ForLt;
37/// # fn expect_lt<F: ForLt>() {}
38/// # struct TypeThatUse<'a>(&'a ());
39/// # expect_lt::<
40/// ForLt!(TypeThatUse<'_>) // Equivalent to `ForLt!(for<'a> TypeThatUse<'a>)`.
41/// # >();
42/// # expect_lt::<
43/// ForLt!(&u32) // Equivalent to `ForLt!(for<'a> &'a u32)`.
44/// # >();
45/// # expect_lt::<
46/// ForLt!(u32) // Equivalent to `ForLt!(for<'a> u32)`.
47/// # >();
48/// ```
49pub trait ForLt {
50    /// The type parameterized by the lifetime.
51    type Of<'a>: 'a;
52}
53pub use macros::ForLt;
54
55/// [`trait@ForLt`] subtrait for types that are covariant over their lifetime parameter.
56///
57/// Provides a safe [`cast_ref`](CovariantForLt::cast_ref) method for types that are proven to be
58/// covariant. The `CovariantForLt!` macro syntax is the same as `ForLt!`.
59///
60/// # Macro
61///
62/// It is not recommended to implement this trait directly.
63/// [`CovariantForLt!`](macro@CovariantForLt) macro is provided to obtain a type that implements
64/// this trait.
65///
66/// The full syntax is
67///
68/// ```
69/// # use kernel::types::CovariantForLt;
70/// # fn expect_lt<F: CovariantForLt>() {}
71/// # struct TypeThatUse<'a>(&'a ());
72/// # expect_lt::<
73/// CovariantForLt!(for<'a> TypeThatUse<'a>)
74/// # >();
75/// ```
76///
77/// which gives a type so that
78/// `<CovariantForLt!(for<'a> TypeThatUse<'a>) as CovariantForLt>::Of<'b>`
79/// is `TypeThatUse<'b>`.
80///
81/// You may also use a short-hand syntax which works similar to lifetime elision.
82/// The macro also accepts types that do not involve a lifetime at all.
83///
84/// ```
85/// # use kernel::types::CovariantForLt;
86/// # fn expect_lt<F: CovariantForLt>() {}
87/// # struct TypeThatUse<'a>(&'a ());
88/// # expect_lt::<
89/// CovariantForLt!(TypeThatUse<'_>) // Equivalent to `CovariantForLt!(for<'a> TypeThatUse<'a>)`.
90/// # >();
91/// # expect_lt::<
92/// CovariantForLt!(&u32) // Equivalent to `CovariantForLt!(for<'a> &'a u32)`.
93/// # >();
94/// # expect_lt::<
95/// CovariantForLt!(u32) // Equivalent to `CovariantForLt!(for<'a> u32)`.
96/// # >();
97/// ```
98///
99/// The macro will attempt to prove that the type is indeed covariant over the lifetime supplied.
100/// When it cannot be syntactically proven, it will emit checks to ask the Rust compiler to prove
101/// it.
102///
103/// ```ignore,compile_fail
104/// # use kernel::types::CovariantForLt;
105/// # fn expect_lt<F: CovariantForLt>() {}
106/// # expect_lt::<
107/// CovariantForLt!(fn(&u32)) // Contravariant, will fail compilation.
108/// # >();
109/// ```
110///
111/// There is a limitation if the type refers to generic parameters; if the macro cannot prove the
112/// covariance syntactically, the emitted checks will fail the compilation as it needs to refer to
113/// the generic parameter but is in a separate item.
114///
115/// ```
116/// # use kernel::types::CovariantForLt;
117/// fn expect_lt<F: CovariantForLt>() {}
118/// # #[allow(clippy::unnecessary_safety_comment, reason = "false positive")]
119/// fn generic_fn<T: 'static>() {
120///     // Syntactically proven by the macro
121///     expect_lt::<CovariantForLt!(&T)>();
122///     // Syntactically proven by the macro
123///     expect_lt::<CovariantForLt!(&KBox<T>)>();
124///     // Cannot be syntactically proven, need to check covariance of `KBox`
125///     // expect_lt::<CovariantForLt!(&KBox<&T>)>();
126/// }
127/// ```
128///
129/// # Safety
130///
131/// `Self::Of<'a>` must be covariant over the lifetime `'a`.
132pub unsafe trait CovariantForLt: ForLt {
133    /// Cast a reference to a shorter lifetime.
134    #[inline(always)]
135    fn cast_ref<'r, 'short: 'r, 'long: 'short>(long: &'r Self::Of<'long>) -> &'r Self::Of<'short> {
136        // SAFETY: This is sound as this trait guarantees covariance.
137        unsafe { core::mem::transmute(long) }
138    }
139}
140pub use macros::CovariantForLt;
141
142/// This is intended to be an "unsafe-to-refer-to" type.
143///
144/// Must only be used by the [`ForLt!`](macro@ForLt) / [`CovariantForLt!`](macro@CovariantForLt)
145/// macros.
146///
147/// `T` is the magic `dyn for<'a> WithLt<'a, TypeThatUse<'a>>` generated by macro.
148///
149/// `WF` is a type that the macro can use to assert some specific type is well-formed.
150///
151/// `N` is to provide the macro a place to emit arbitrary items, in case it needs to prove
152/// additional properties. [`ForLt!`](macro@ForLt) emits `N = 0`;
153/// [`CovariantForLt!`](macro@CovariantForLt) emits `N = 1` after a covariance proof.
154#[doc(hidden)]
155pub struct UnsafeForLtImpl<T: ?Sized, WF, const N: usize>(PhantomData<(WF, T)>);
156
157// This is a helper trait for implementation of `ForLt` / `CovariantForLt` to be able to use HRTB.
158#[doc(hidden)]
159pub trait WithLt<'a> {
160    type Of: 'a;
161}
162
163impl<T: ?Sized + for<'a> WithLt<'a>, WF, const N: usize> ForLt for UnsafeForLtImpl<T, WF, N> {
164    type Of<'a> = <T as WithLt<'a>>::Of;
165}
166
167// SAFETY: In `CovariantForLt!` macro, a covariance proof is generated in the `N` const generic
168// and it will fail to evaluate if the type is not covariant. Only `N = 1` gets this impl.
169unsafe impl<T: ?Sized + for<'a> WithLt<'a>, WF> CovariantForLt for UnsafeForLtImpl<T, WF, 1> {}
kernel/types/for_lt.rs

kernel/types/
for_lt.rs
