more docs & make projection traits unsafe

Author: BennoLossin

examples/kernel_mutex_rcu.rs

@@ -97,7 +97,7 @@ mod rcu {
         type Safety = Safe;
     }
 
-    impl<'a, T, U, F> Project<F> for &'a RcuMutex<T>
+    unsafe impl<'a, T, U, F> Project<F> for &'a RcuMutex<T>
     where
         F: UnalignedField<Base = T, Type = Rcu<U>>,
         U: 'a,
@@ -143,7 +143,7 @@ struct MyDriver {
 
 impl MyDriver {
     fn flush_sensitivity<'a>(&'a self, rcu_guard: &'a RcuGuard) -> u8 {
-        let buf = &self.buf;
+        let buf: &'a RcuMutex<Buffer> = &self.buf;
         start_proj!(buf);
         // Here we use the special projections set up for `Mutex` with fields of type `Rcu<T>`.
         let cfg: &Rcu<Box<BufferConfig>> = p!(@buf->cfg);
@@ -158,14 +158,14 @@ impl MyDriver {
     }
 
     fn set_buffer_config(&self, flush_sensitivity: u8) {
-        // Our `Mutex` pins the value.
+        // `RcuMutex` pins the value.
         let mut guard: Pin<RcuMutexGuard<'_, Buffer>> = self.buf.lock();
-        let mut buf = guard.as_mut();
+        let mut buf: Pin<&mut Buffer> = guard.as_mut();
         start_proj!(mut buf);
         // We can use pin-projections since we marked `cfg` as `#[pin]`
         let cfg: Pin<&mut Rcu<Box<BufferConfig>>> = p!(@mut buf->cfg);
         cfg.set(Box::new(BufferConfig { flush_sensitivity }));
-        // ^^ this returns an `Old<Box<BufferConfig>>` and runs `synchronize_rcu` on drop.
+        //  ^^^ this returns an `Old<Box<BufferConfig>>` and runs `synchronize_rcu` on drop.
     }
 }
 

examples/kernel_ptr.rs

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

src/ops.rs

@@ -13,8 +13,20 @@ pub trait Projectable: Sized {
     type Inner: ?Sized;
 }
 
+/// Marks project operations as safe.
+///
+/// # Safety
+///
+/// * The `@base->field` and `@mut base->field` operations implemented by the [`Project`] and
+///   [`ProjectMut`] traits must not have additional safety requirements.
+pub unsafe trait SafeProject: Projectable {}
+
 /// Shared projection operation `@base->field`.
-pub trait Project<F>: Projectable
+///
+/// # Safety
+///
+///
+pub unsafe trait Project<F>: Projectable
 where
     F: UnalignedField<Base = Self::Inner>,
 {
@@ -28,13 +40,20 @@ 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
+    ///   operations.
+    /// * for the duration of `'a`, the value at `this` is not mutably projected with `F`.
     unsafe fn project<'a>(this: *const Self) -> Self::Output<'a>
     where
         Self: 'a;
 }
 
 /// Exclusive projection operation `@mut base->field`.
-pub trait ProjectMut<F>: Projectable
+///
+/// # Safety
+///
+///
+pub unsafe trait ProjectMut<F>: Projectable
 where
     F: UnalignedField<Base = Self::Inner>,
 {
@@ -48,19 +67,13 @@ where
     /// # Safety
     ///
     /// * `this` must be a dereferenceable pointer pointing at a valid value of `Self`.
-    /// * this function must only be called once.
+    /// * for the duration of `'a`, the value at `this` is only used by other projection
+    ///   operations for fields other than `F`.
     unsafe fn project_mut<'a>(this: *mut Self) -> Self::OutputMut<'a>
     where
         Self: 'a;
 }
 
-/// Marks project operations as safe.
-///
-/// # Safety
-///
-/// * the `@base->field` and `@mut base->field` operations must be safe.
-pub unsafe trait SafeProject: Projectable {}
-
 include!("./projections/maybe_uninit.rs");
 include!("./projections/non_null.rs");
 include!("./projections/pin.rs");

src/projections/maybe_uninit.rs

@@ -6,7 +6,7 @@ impl<T> Projectable for &mut MaybeUninit<T> {
 
 unsafe impl<T> SafeProject for &mut MaybeUninit<T> {}
 
-impl<'a, T, F> ProjectMut<F> for &'a mut MaybeUninit<T>
+unsafe 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,7 @@ impl<T: ?Sized> Projectable for NonNull<T> {
     type Inner = T;
 }
 
-impl<T, F> Project<F> for NonNull<T>
+unsafe impl<T, F> Project<F> for NonNull<T>
 where
     F: UnalignedField<Base = T>,
     F::Type: Sized,

src/projections/pin.rs

@@ -6,7 +6,7 @@ impl<T> Projectable for Pin<&mut T> {
 
 unsafe impl<T> SafeProject for Pin<&mut T> {}
 
-impl<'a, T, F> Project<F> for Pin<&'a mut T>
+unsafe 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 +26,7 @@ where
     }
 }
 
-impl<'a, T, F> ProjectMut<F> for Pin<&'a mut T>
+unsafe 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,7 @@ impl<T> Projectable for *const T {
     type Inner = T;
 }
 
-impl<T, F> Project<F> for *const T
+unsafe impl<T, F> Project<F> for *const T
 where
     F: UnalignedField<Base = T>,
     F::Type: Sized,
@@ -25,7 +25,7 @@ impl<T> Projectable for *mut T {
     type Inner = T;
 }
 
-impl<T, F> Project<F> for *mut T
+unsafe impl<T, F> Project<F> for *mut T
 where
     F: UnalignedField<Base = T>,
     F::Type: Sized,

src/projections/unsafe_cell.rs

@@ -4,7 +4,7 @@ impl<T> Projectable for &UnsafeCell<T> {
     type Inner = T;
 }
 
-impl<'a, T, F> Project<F> for &'a UnsafeCell<T>
+unsafe impl<'a, T, F> Project<F> for &'a UnsafeCell<T>
 where
     F: Field<Base = T>,
     F::Type: 'a + Sized,