[eclipse-iceoryx#139] Add documentation

Author: elfenpiff

iceoryx2-cal/src/event/common.rs

@@ -259,7 +259,7 @@ pub mod details {
                     id, self.storage.get().id_tracker.trigger_id_max());
             }
 
-            self.storage.get().id_tracker.add(id)?;
+            unsafe { self.storage.get().id_tracker.add(id)? };
             Ok(unsafe { self.storage.get().signal_mechanism.notify()? })
         }
     }
@@ -382,7 +382,7 @@ pub mod details {
             &self,
         ) -> Result<Option<crate::event::TriggerId>, crate::event::ListenerWaitError> {
             while unsafe { self.storage.get().signal_mechanism.try_wait()? } {}
-            Ok(self.storage.get().id_tracker.acquire())
+            Ok(unsafe { self.storage.get().id_tracker.acquire() })
         }
 
         fn timed_wait(
@@ -394,7 +394,7 @@ pub mod details {
             }
 
             if unsafe { self.storage.get().signal_mechanism.timed_wait(timeout)? } {
-                return Ok(self.storage.get().id_tracker.acquire());
+                return Ok(unsafe { self.storage.get().id_tracker.acquire() });
             }
 
             Ok(None)
@@ -408,7 +408,7 @@ pub mod details {
             }
 
             unsafe { self.storage.get().signal_mechanism.blocking_wait()? };
-            Ok(self.storage.get().id_tracker.acquire())
+            Ok(unsafe { self.storage.get().id_tracker.acquire() })
         }
     }
 

iceoryx2-cal/src/event/id_tracker/bit_set.rs

@@ -21,7 +21,7 @@ impl IdTracker for RelocatableBitSet {
         TriggerId::new(self.capacity() as u64)
     }
 
-    fn add(&self, id: TriggerId) -> Result<(), NotifierNotifyError> {
+    unsafe fn add(&self, id: TriggerId) -> Result<(), NotifierNotifyError> {
         if self.trigger_id_max() <= id {
             fail!(from self, with NotifierNotifyError::TriggerIdOutOfBounds,
                 "Unable to set bit {:?} since it is out of bounds (max = {:?}).",
@@ -32,11 +32,11 @@ impl IdTracker for RelocatableBitSet {
         Ok(())
     }
 
-    fn acquire_all<F: FnMut(TriggerId)>(&self, mut callback: F) {
+    unsafe fn acquire_all<F: FnMut(TriggerId)>(&self, mut callback: F) {
         self.reset_all(|bit_index| callback(TriggerId::new(bit_index as u64)))
     }
 
-    fn acquire(&self) -> Option<TriggerId> {
+    unsafe fn acquire(&self) -> Option<TriggerId> {
         match self.reset_next() {
             Some(id) => Some(TriggerId::new(id as u64)),
             None => None,

iceoryx2-cal/src/event/id_tracker/mod.rs

@@ -18,9 +18,34 @@ use iceoryx2_bb_elementary::relocatable_container::RelocatableContainer;
 
 use super::{NotifierNotifyError, TriggerId};
 
+/// The [`SignalMechanism`] is a building block for [`crate::event::Event`]
+/// concept. Its task is to track the origin of the signal that was sent
+/// via the [`crate::event::signal_mechanism::SignalMechanism`].
 pub trait IdTracker: RelocatableContainer + Send + Sync + Debug {
+    /// Returns the max value of a [`TriggerId`] that can be tracked with the
+    /// [`IdTracker`].
     fn trigger_id_max(&self) -> TriggerId;
-    fn add(&self, id: TriggerId) -> Result<(), NotifierNotifyError>;
-    fn acquire(&self) -> Option<TriggerId>;
-    fn acquire_all<F: FnMut(TriggerId)>(&self, callback: F);
+
+    /// Tracks the provided [`TriggerId`].
+    ///
+    /// # Safety
+    ///  * underlying container must be initialized with [`RelocatableContainer::init()`]
+    ///
+    unsafe fn add(&self, id: TriggerId) -> Result<(), NotifierNotifyError>;
+
+    /// Acquires a tracked [`TriggerId`]. When no [`TriggerId`]s are tracked
+    /// or all tracked [`TriggerId`]s have been acquired it returns [`None`].
+    ///
+    /// # Safety
+    ///  * underlying container must be initialized with [`RelocatableContainer::init()`]
+    ///
+    unsafe fn acquire(&self) -> Option<TriggerId>;
+
+    /// Acquires all tracked [`TriggerId`]s and calls for everyone the user
+    /// provided callback with the [`TriggerId`] as input argument.
+    ///
+    /// # Safety
+    ///  * underlying container must be initialized with [`RelocatableContainer::init()`]
+    ///
+    unsafe fn acquire_all<F: FnMut(TriggerId)>(&self, callback: F);
 }

iceoryx2-cal/src/event/signal_mechanism/mod.rs

@@ -16,6 +16,9 @@ use super::{ListenerCreateError, ListenerWaitError, NotifierNotifyError};
 
 pub mod semaphore;
 
+/// The [`SignalMechanism`] is a building block for [`crate::event::Event`]
+/// concept. Its task is to
+/// wake up another process/thread with a signal.
 pub trait SignalMechanism: Send + Sync + Debug {
     /// Creates a [`SignalMechanism`]. It cannot be used until
     /// [`SignalMechanism::init()`] was called.

iceoryx2-cal/tests/event_id_tracker_tests.rs

@@ -42,12 +42,12 @@ mod event_id_tracker {
         let sut = unsafe { Sut::new_uninit(CAPACITY) };
         assert_that!(unsafe { sut.init(memory.allocator()) }, is_ok);
 
-        assert_that!(sut.acquire(), eq None);
+        assert_that!(unsafe { sut.acquire() }, eq None);
         for i in 0..CAPACITY {
             let id = TriggerId::new(i as u64);
-            assert_that!(sut.add(id), is_ok);
-            assert_that!(sut.acquire(), eq Some(id));
-            assert_that!(sut.acquire(), is_none);
+            assert_that!(unsafe { sut.add(id) }, is_ok);
+            assert_that!(unsafe { sut.acquire() }, eq Some(id));
+            assert_that!(unsafe { sut.acquire() }, is_none);
         }
     }
 
@@ -61,17 +61,17 @@ mod event_id_tracker {
 
         for i in 0..CAPACITY {
             let id = TriggerId::new((i as u64).min(sut.trigger_id_max().as_u64()));
-            assert_that!(sut.add(id), is_ok);
+            assert_that!(unsafe { sut.add(id) }, is_ok);
         }
 
         let mut ids = HashSet::new();
         for _ in 0..CAPACITY {
-            let result = sut.acquire().unwrap();
+            let result = unsafe { sut.acquire().unwrap() };
             assert_that!(result, le sut.trigger_id_max());
             assert_that!(ids.insert(result), eq true);
         }
 
-        assert_that!(sut.acquire(), is_none);
+        assert_that!(unsafe { sut.acquire() }, is_none);
     }
 
     #[test]
@@ -84,17 +84,19 @@ mod event_id_tracker {
 
         for i in 0..CAPACITY {
             let id = TriggerId::new((i as u64).min(sut.trigger_id_max().as_u64()));
-            assert_that!(sut.add(id), is_ok);
+            assert_that!(unsafe { sut.add(id) }, is_ok);
         }
 
         let mut ids = HashSet::new();
-        sut.acquire_all(|id| {
-            assert_that!(id, le sut.trigger_id_max());
-            assert_that!(ids.insert(id), eq true);
-        });
+        unsafe {
+            sut.acquire_all(|id| {
+                assert_that!(id, le sut.trigger_id_max());
+                assert_that!(ids.insert(id), eq true);
+            })
+        };
 
         let mut callback_called = false;
-        sut.acquire_all(|_| callback_called = true);
+        unsafe { sut.acquire_all(|_| callback_called = true) };
         assert_that!(callback_called, eq false);
 
         assert_that!(ids, len CAPACITY);
@@ -110,20 +112,22 @@ mod event_id_tracker {
 
         for i in 0..CAPACITY {
             let id = TriggerId::new((i as u64).min(sut.trigger_id_max().as_u64()));
-            assert_that!(sut.add(id), is_ok);
+            assert_that!(unsafe { sut.add(id) }, is_ok);
         }
 
         let mut ids = HashSet::new();
         for _ in 0..CAPACITY / 2 {
-            let result = sut.acquire().unwrap();
+            let result = unsafe { sut.acquire().unwrap() };
             assert_that!(result, le sut.trigger_id_max());
             assert_that!(ids.insert(result), eq true);
         }
 
-        sut.acquire_all(|id| {
-            assert_that!(id, le sut.trigger_id_max());
-            assert_that!(ids.insert(id), eq true);
-        });
+        unsafe {
+            sut.acquire_all(|id| {
+                assert_that!(id, le sut.trigger_id_max());
+                assert_that!(ids.insert(id), eq true);
+            })
+        };
 
         assert_that!(ids, len CAPACITY);
     }