stash

util/src/ipc/shm/shared_memory_segment.rs

@@ -7,7 +7,7 @@ use std::{
 
 use crate::{
     int::u64uint::usize_to_u64,
-    ptr::{ReadMemVolatileExt, WriteMemVolatileExt},
+    ptr::{ReadMemVolatile, WriteMemVolatile},
     result::OkExt,
     secret_memory::{
         fd::SecretMemfdConfig,

util/src/mem.rs

@@ -313,10 +313,60 @@ pub trait CopyExt: Copy {
 
 impl<T: Copy> CopyExt for T {}
 
+/// Helper trait for applying a mutating closure/function to a mutable reference
+///
+/// # Examples
+///
+/// ```rust
+/// fn plus_two_mul_three(v: u64) -> u64 {
+///     (v + 2) * 3
+/// }
+/// 
+/// fn inconvenient_example(v: &mut u64) {
+///     *v = plus_two_mul_three(*v);
+/// }
+/// 
+/// fn convenient_example(v: &mut u64) {
+///     v.mutate(plus_two_mul_three);
+/// }
+/// 
+/// let mut x = 0;
+/// inconvenient_example(&mut x);
+/// assert_eq!(x, 6);
+/// convenient_example(&mut x);
+/// assert_eq!(x, 24);
+/// 
+/// x = 0;
+/// 
+/// x.mutate(plus_two_mul_three);
+/// assert_eq!(x, 6);
+/// x.mutate(|v| (v + 2) * 3);
+/// assert_eq!(x, 24);
+/// 
+/// x = 0;
+/// 
+/// let y = &mut x;
+/// y.mutate(plus_two_mul_three);
+/// assert_eq!(x, 6);
+/// 
+/// struct Cont {
+///     x: u64,
+/// }
+/// 
+/// impl Cont {
+///     fn x_mut(&mut self) -> &mut u64 {
+///         &mut self.x
+///     }
+/// }
+/// 
+/// let mut s = Cont { x: 0 };
+/// s.x_mut().mutate(|v| (v + 2) * 3);
+/// ```
 pub trait MutateRefExt: DerefMut
 where
     Self::Target: Sized,
 {
+    /// Directly mutate a reference
     fn mutate<F: FnOnce(Self::Target) -> Self::Target>(self, f: F) -> Self;
 }
 
@@ -332,56 +382,6 @@ where
     }
 }
 
-#[test]
-fn test_mutate() {
-    fn plus_two_mul_three(v: u64) -> u64 {
-        (v + 2) * 3
-    }
-
-    fn inconvenient_example(v: &mut u64) {
-        *v = plus_two_mul_three(*v);
-    }
-
-    fn convenient_example(v: &mut u64) {
-        v.mutate(plus_two_mul_three);
-    }
-
-    let mut x = 0;
-    inconvenient_example(&mut x);
-    assert_eq!(x, 6);
-    convenient_example(&mut x);
-    assert_eq!(x, 24);
-
-    x = 0;
-
-    x.mutate(plus_two_mul_three);
-    assert_eq!(x, 6);
-    x.mutate(|v| (v + 2) * 3);
-    assert_eq!(x, 24);
-
-    x = 0;
-
-    let y = &mut x;
-    y.mutate(plus_two_mul_three);
-    assert_eq!(x, 6);
-
-    struct Foo {
-        x: u64,
-    }
-
-    impl Foo {
-        fn x_mut(&mut self) -> &mut u64 {
-            &mut self.x
-        }
-    }
-
-    let mut foo = Foo { x: 0 };
-    foo.x_mut().mutate(|v| (v + 2) * 3);
-}
-
-#[test]
-fn test_copy() {}
-
 #[cfg(test)]
 mod test_forgetting {
     use crate::mem::Forgetting;

util/src/ptr/volatile.rs

@@ -1,10 +1,20 @@
 //! Utilities relating to volatile reads/writes on pointers
 
-pub trait ReadMemVolatileExt<T> {
+/// Read from a memory location using 
+/// [pointer::read_volatile] in a loop and store the
+/// results in the given slice
+pub trait ReadMemVolatile<T> {
+    /// Read from a memory location using 
+    /// [pointer::read_volatile] in a loop and store the
+    /// results in an array
+    ///
+    /// # Safety
+    ///
+    /// Refer to [pointer::read_volatile]
     unsafe fn read_mem_volatile(self, dst: &mut [T]);
 }
 
-impl<T> ReadMemVolatileExt<T> for *const T {
+impl<T> ReadMemVolatile<T> for *const T {
     unsafe fn read_mem_volatile(self, dst: &mut [T]) {
         for (idx, dst) in dst.iter_mut().enumerate() {
             *dst = unsafe { self.add(idx).read_volatile() };
@@ -12,17 +22,27 @@ impl<T> ReadMemVolatileExt<T> for *const T {
     }
 }
 
-impl<T> ReadMemVolatileExt<T> for *mut T {
+impl<T> ReadMemVolatile<T> for *mut T {
     unsafe fn read_mem_volatile(self, dst: &mut [T]) {
         unsafe { self.cast_const().read_mem_volatile(dst) }
     }
 }
 
-pub trait WriteMemVolatileExt<T>: ReadMemVolatileExt<T> {
+/// Write to a memory location using 
+/// [pointer::write_volatile] in a loop
+/// and store the resulting values in the given slice
+pub trait WriteMemVolatile<T>: ReadMemVolatile<T> {
+    /// Write to a memory location using 
+    /// [pointer::write_volatile] in a loop
+    /// and store the resulting values in the given slice
+    ///
+    /// # Safety
+    ///
+    /// Refer to [pointer::write_volatile]
     unsafe fn write_mem_volatile(self, src: &[T]);
 }
 
-impl<T: Copy> WriteMemVolatileExt<T> for *mut T {
+impl<T: Copy> WriteMemVolatile<T> for *mut T {
     unsafe fn write_mem_volatile(self, src: &[T]) {
         for (idx, src) in src.iter().enumerate() {
             unsafe { self.add(idx).write_volatile(*src) }

util/src/ringbuf/concurrent/framework.rs

@@ -75,8 +75,7 @@ impl<'a> ConcurrentPipeOperation<'a> {
         self.inner_buf().len()
     }
 
-    pub fn scheduler_op(&self) -> crate::ringbuf::sched::OperationType {
-        use crate::ringbuf::sched::OperationType;
+    pub fn scheduler_op(&self) -> OperationType {
         match self {
             ConcurrentPipeOperation::Read(_) => OperationType::Read,
             ConcurrentPipeOperation::Write(_) => OperationType::Write,
@@ -145,16 +144,16 @@ impl<Core: ConcurrentPipeCore> ConcurrentPipeImpl<Core> {
         if let Diff::Different(old, new) = diff {
             store_to_ctr
                 .compare_exchange(old, new, ord_store_succ, ord_store_fail)
-                .map_err(|actual| {
-                    InconsistentRingBufferStateError::ConcurrrentAccess {
+                .map_err(
+                    |actual| InconsistentRingBufferStateError::ConcurrrentAccess {
                         operation_type: op.scheduler_op(),
                         scheduled_ops: ops,
                         scheduler_state: sched,
                         expected_counter_value: old,
                         actual_counter_value: actual,
                         new_counter_value_tried_to_set: new,
-                    }
-                })?;
+                    },
+                )?;
         }
 
         ops.cumulative_operation_length().usize().ok()