[eclipse-iceoryx#139] Add detailed explanation and reworded doc

Author: elfenpiff

iceoryx2-cal/src/event/common.rs

@@ -383,7 +383,13 @@ pub mod details {
         fn try_wait(
             &self,
         ) -> Result<Option<crate::event::TriggerId>, crate::event::ListenerWaitError> {
-            // collect all notifications until no more are available
+            // collect all notifications until no more are available, otherwise it is possible
+            // that blocking_wait and timed_wait are becoming non-blocking when the same id is
+            // triggered multiple times in combination with a bitset id_tracker since the bit is
+            // set only once but the signal is triggered whenever the user sets the bit.
+            //
+            // of course one could check if the id_tracker has already set the bit, but this is
+            // not possible on every implemenation. a bitset can check it a mpmc::queue maybe not.
             while unsafe { self.storage.get().signal_mechanism.try_wait()? } {}
             Ok(unsafe { self.storage.get().id_tracker.acquire() })
         }

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

@@ -27,22 +27,22 @@ pub trait SignalMechanism: Send + Sync + Debug {
     /// Initializes the [`SignalMechanism`] in place.
     ///
     /// # Safety
-    ///   * [`SignalMechanism::init()`] must not be called before
+    ///   * [`SignalMechanism::init()`] must called exactly once before all other methods
     unsafe fn init(&mut self) -> Result<(), ListenerCreateError>;
 
     /// Notifies the counter-part of the [`SignalMechanism`] meaning
     /// that a [`SignalMechanism::try_wait()`], [`SignalMechanism::timed_wait()`]
     /// or [`SignalMechanism::blocking_wait()`] call wakes up and returns true.
     ///
     /// # Safety
-    ///   * [`SignalMechanism::init()`] must be called before
+    ///   * [`SignalMechanism::init()`] must have been called exactly once
     ///   * Must not be dropped while in use from another process
     unsafe fn notify(&self) -> Result<(), NotifierNotifyError>;
 
     /// When a signal was received it returns true, otherwise false.
     ///
     /// # Safety
-    ///   * [`SignalMechanism::init()`] must be called before
+    ///   * [`SignalMechanism::init()`] must have been called exactly once
     ///   * Must not be dropped while in use from another process
     unsafe fn try_wait(&self) -> Result<bool, ListenerWaitError>;
 
@@ -54,7 +54,7 @@ pub trait SignalMechanism: Send + Sync + Debug {
     /// it returns [`ListenerWaitError::InterruptSignal`].
     ///
     /// # Safety
-    ///   * [`SignalMechanism::init()`] must be called before
+    ///   * [`SignalMechanism::init()`] must have been called exactly once
     ///   * Must not be dropped while in use from another process
     unsafe fn timed_wait(&self, timeout: Duration) -> Result<bool, ListenerWaitError>;
 
@@ -64,7 +64,7 @@ pub trait SignalMechanism: Send + Sync + Debug {
     /// it returns [`ListenerWaitError::InterruptSignal`].
     ///
     /// # Safety
-    ///   * [`SignalMechanism::init()`] must called before
+    ///   * [`SignalMechanism::init()`] must have been called exactly once
     ///   * Must not be dropped while in use from another process
     unsafe fn blocking_wait(&self) -> Result<(), ListenerWaitError>;
 }