docs & safety improvements

Author: BennoLossin

examples/cpp_ref/cpp_ref.rs

@@ -31,7 +31,7 @@ unsafe impl<T: ?Sized> ProjectableExt for CppMutRef<T> {
     type Safety = Safe;
 }
 
-unsafe impl<T, F> ProjectMut<F> for CppMutRef<T>
+impl<T, F> ProjectMut<F> for CppMutRef<T>
 where
     F: Field<Base = T>,
     F::Type: Sized,

examples/kernel_mutex_rcu/rcu.rs

@@ -90,7 +90,7 @@ unsafe impl<T> ProjectableExt for &RcuMutex<T> {
     type Safety = Safe;
 }
 
-unsafe impl<'a, T, U, F> Project<F> for &'a RcuMutex<T>
+impl<'a, T, U, F> Project<F> for &'a RcuMutex<T>
 where
     F: UnalignedField<Base = T, Type = Rcu<U>>,
     U: 'a,

examples/kernel_ptr.rs

@@ -26,7 +26,7 @@ unsafe impl<'a, T: 'a> ProjectableExt for Ptr<'a, T> {
     type Safety = Safe;
 }
 
-unsafe impl<'a, T, F> Project<F> for Ptr<'a, T>
+impl<'a, T, F> Project<F> for Ptr<'a, T>
 where
     T: 'a,
     F: Field<Base = T>,

src/marker.rs

@@ -1,4 +1,4 @@
-/// A field of a `struct`, `union` or tuple.
+/// Type representing a field of a `struct`, `union` or tuple.
 ///
 /// # Safety
 ///
@@ -15,15 +15,15 @@ pub unsafe trait UnalignedField: Sized {
     const OFFSET: usize;
 }
 
-/// An aligned field of a `struct`, `union` or tuple.
+/// Type representing an aligned field of a `struct`, `union` or tuple.
 ///
 /// # Safety
 ///
 /// Given a well-aligned value of type `Self::Base`, the field at `Self::OFFSET` of type
 /// `Self::Type` is well-aligned.
 pub unsafe trait Field: UnalignedField {}
 
-/// A field of a `struct`, `union` or tuple with structural pinning information.
+/// Type representing a field of a `struct`, `union` or tuple with structural pinning information.
 ///
 /// # Safety
 ///

src/ops.rs

@@ -3,30 +3,30 @@ use crate::{
     marker::{Field, PinableField, UnalignedField},
 };
 
-/// Type supporting projections.
+/// Type supporting field projections.
 ///
-/// The exact kind of projection is governed by [`Project`] and [`ProjectMut`]. This trait only
-/// gives the compiler access to the `Self::Inner` type which is the type containing the projected
-/// fields. So given an expression `base` of type `Self`, then the `field` ident in the expressions
-/// `@base->field` and `@mut base->field` refer to a field of the type `Self::Inner`.
+/// The exact kind of field projection is governed by [`Project`] and [`ProjectMut`]. This trait
+/// only gives the compiler access to the `Self::Inner` type which is the type containing the
+/// potentially projectable fields. So given an expression `base` of type `Self`, then the `field`
+/// ident in the expressions `@base->field` and `@mut base->field` refer to a field of the type
+/// `Self::Inner`.
+///
+/// If the projection `@base->field` is available still depends on weather `Self` implements
+/// `Project<field_of!(Self::Inner, field)>`.
 pub trait Projectable: Sized {
     type Inner: ?Sized;
 }
 
-/// Marks project operations as safe.
+/// Marks project operations on `Self` as safe.
 ///
 /// # Safety
 ///
-/// * The `@base->field` and `@mut base->field` operations implemented by the [`Project`] and
-///   [`ProjectMut`] traits must not have additional safety requirements.
+/// * The [`Project::project`] and [`ProjectMut::project_mut`] functions implemented for `Self`
+///   must not have additional safety requirements.
 pub unsafe trait SafeProject: Projectable {}
 
 /// Shared projection operation `@base->field`.
-///
-/// # Safety
-///
-///
-pub unsafe trait Project<F>: Projectable
+pub trait Project<F>: Projectable
 where
     F: UnalignedField<Base = Self::Inner>,
 {
@@ -39,21 +39,19 @@ where
     ///
     /// # Safety
     ///
-    /// * `this` must be a dereferenceable pointer pointing at a valid value of `Self`.
+    /// * `this` must be a valid pointer pointing at a valid value of `Self`.
     /// * for the duration of `'a`, the value at `this` is only used by other projection
     ///   operations.
     /// * for the duration of `'a`, the value at `this` is not mutably projected with `F`.
+    /// * Implementers may impose additional safety requirements. These must be documented on the
+    ///   implementation of this trait.
     unsafe fn project<'a>(this: *const Self) -> Self::Output<'a>
     where
         Self: 'a;
 }
 
 /// Exclusive projection operation `@mut base->field`.
-///
-/// # Safety
-///
-///
-pub unsafe trait ProjectMut<F>: Projectable
+pub trait ProjectMut<F>: Projectable
 where
     F: UnalignedField<Base = Self::Inner>,
 {
@@ -66,9 +64,11 @@ where
     ///
     /// # Safety
     ///
-    /// * `this` must be a dereferenceable pointer pointing at a valid value of `Self`.
-    /// * for the duration of `'a`, the value at `this` is only used by other projection
+    /// * `this` must be a valid pointer pointing at a valid value of `Self`.
+    /// * For the duration of `'a`, the value at `this` is only used by other projection
     ///   operations for fields other than `F`.
+    /// * Implementers may impose additional safety requirements. These must be documented on the
+    ///   implementation of this trait.
     unsafe fn project_mut<'a>(this: *mut Self) -> Self::OutputMut<'a>
     where
         Self: 'a;

src/projections/maybe_uninit.rs

@@ -4,9 +4,11 @@ impl<T> Projectable for &mut MaybeUninit<T> {
     type Inner = T;
 }
 
+// SAFETY: no additional safety requirements on `Project[Mut]::project[_mut]`.
 unsafe impl<T> SafeProject for &mut MaybeUninit<T> {}
 
-unsafe impl<'a, T, F> ProjectMut<F> for &'a mut MaybeUninit<T>
+// No additional safety requirements for `project_mut`.
+impl<'a, T, F> ProjectMut<F> for &'a mut MaybeUninit<T>
 where
     F: Field<Base = T>,
     F::Type: Sized + 'a,

src/projections/non_null.rs

@@ -4,7 +4,10 @@ impl<T: ?Sized> Projectable for NonNull<T> {
     type Inner = T;
 }
 
-unsafe impl<T, F> Project<F> for NonNull<T>
+// Additional safety requirements for `project`:
+// * The pointer pointed at by `this` must point to an allocated object at least as large as
+//   `size_of::<T>()`.
+impl<T, F> Project<F> for NonNull<T>
 where
     F: UnalignedField<Base = T>,
     F::Type: Sized,

src/projections/pin.rs

@@ -4,9 +4,11 @@ impl<T> Projectable for Pin<&mut T> {
     type Inner = T;
 }
 
+// SAFETY: no additional safety requirements on `Project[Mut]::project[_mut]`.
 unsafe impl<T> SafeProject for Pin<&mut T> {}
 
-unsafe impl<'a, T, F> Project<F> for Pin<&'a mut T>
+// No additional safety requirements for `project_mut`.
+impl<'a, T, F> Project<F> for Pin<&'a mut T>
 where
     F: PinableField<Base = T> + Field<Base = T>,
     F::Type: Sized + 'a,
@@ -26,7 +28,8 @@ where
     }
 }
 
-unsafe impl<'a, T, F> ProjectMut<F> for Pin<&'a mut T>
+// No additional safety requirements for `project_mut`.
+impl<'a, T, F> ProjectMut<F> for Pin<&'a mut T>
 where
     F: PinableField<Base = T> + Field<Base = T>,
     F::Type: Sized + 'a,

src/projections/raw_ptr.rs

@@ -2,7 +2,10 @@ impl<T> Projectable for *const T {
     type Inner = T;
 }
 
-unsafe impl<T, F> Project<F> for *const T
+// Additional safety requirements for `project`:
+// * The pointer pointed at by `this` must point to an allocated object at least as large as
+//   `size_of::<T>()`.
+impl<T, F> Project<F> for *const T
 where
     F: UnalignedField<Base = T>,
     F::Type: Sized,
@@ -25,7 +28,10 @@ impl<T> Projectable for *mut T {
     type Inner = T;
 }
 
-unsafe impl<T, F> Project<F> for *mut T
+// Additional safety requirements for `project`:
+// * The pointer pointed at by `this` must point to an allocated object at least as large as
+//   `size_of::<T>()`.
+impl<T, F> Project<F> for *mut T
 where
     F: UnalignedField<Base = T>,
     F::Type: Sized,

src/projections/unsafe_cell.rs

@@ -4,7 +4,8 @@ impl<T> Projectable for &UnsafeCell<T> {
     type Inner = T;
 }
 
-unsafe impl<'a, T, F> Project<F> for &'a UnsafeCell<T>
+// No additional safety requirements for `project_mut`.
+impl<'a, T, F> Project<F> for &'a UnsafeCell<T>
 where
     F: Field<Base = T>,
     F::Type: 'a + Sized,