Streamline API for Timer

Signed-off-by: Michael X. Grey <[email protected]>

Author: mxgrey

rclrs/src/error.rs

@@ -32,6 +32,10 @@ pub enum RclrsError {
     },
     /// It was attempted to add a waitable to a wait set twice.
     AlreadyAddedToWaitSet,
+    /// A negative duration was obtained from rcl which should have been positive.
+    ///
+    /// The value represents nanoseconds.
+    NegativeDuration(i64),
 }
 
 impl Display for RclrsError {
@@ -48,6 +52,9 @@ impl Display for RclrsError {
                     "Could not add entity to wait set because it was already added to a wait set"
                 )
             }
+            RclrsError::NegativeDuration(duration) => {
+                write!(f, "A duration was negative when it should not have been: {duration:?}")
+            }
         }
     }
 }
@@ -80,6 +87,7 @@ impl Error for RclrsError {
             RclrsError::UnknownRclError { msg, .. } => msg.as_ref().map(|e| e as &dyn Error),
             RclrsError::StringContainsNul { err, .. } => Some(err).map(|e| e as &dyn Error),
             RclrsError::AlreadyAddedToWaitSet => None,
+            RclrsError::NegativeDuration(_) => None,
         }
     }
 }

rclrs/src/node.rs

@@ -16,7 +16,8 @@ use crate::{
     rcl_bindings::*, Client, ClientBase, Clock, Context, ContextHandle, GuardCondition, LogParams,
     Logger, ParameterBuilder, ParameterInterface, ParameterVariant, Parameters, Publisher,
     QoSProfile, RclrsError, Service, ServiceBase, Subscription, SubscriptionBase,
-    SubscriptionCallback, TimeSource, Timer, TimerCallback, ToLogParams, ENTITY_LIFECYCLE_MUTEX,
+    SubscriptionCallback, TimeSource, Timer, IntoTimerOptions, AnyTimerCallback,
+    TimerCallRepeating, TimerCallOnce, ToLogParams, ENTITY_LIFECYCLE_MUTEX,
 };
 
 // SAFETY: The functions accessing this type, including drop(), shouldn't care about the thread
@@ -341,22 +342,23 @@ impl Node {
         Ok(subscription)
     }
 
-    /// Creates a [`Timer`][1].
+    /// Creates a [`Timer`].
+    ///
+    /// For more ergonomic usage see also:
+    /// * [`Self::create_timer_repeating`]
+    /// * [`Self::create_timer_oneshot`]
+    /// * [`Self::create_timer_inert`]
     ///
-    /// [1]: crate::Timer
     /// TODO: make timer's lifetime depend on node's lifetime.
-    pub fn create_timer(
+    pub fn create_timer<'a>(
         &self,
-        period_ns: i64,
-        context: &Context,
-        callback: Option<TimerCallback>,
-        clock: Option<Clock>,
+        options: impl IntoTimerOptions<'a>,
+        callback: AnyTimerCallback,
     ) -> Result<Arc<Timer>, RclrsError> {
-        let clock_used = match clock {
-            Some(value) => value,
-            None => self.get_clock(),
-        };
-        let timer = Timer::new(&clock_used, &context, period_ns, callback)?;
+        let options = options.into_timer_options();
+        let clock = options.clock.as_clock(self);
+
+        let timer = Timer::new(&self.handle.context_handle, options.period, clock, callback)?;
         let timer = Arc::new(timer);
         self.timers_mtx
             .lock()
@@ -365,6 +367,48 @@ impl Node {
         Ok(timer)
     }
 
+    /// Create a [`Timer`] with a repeating callback.
+    ///
+    /// See also:
+    /// * [`Self::create_timer_oneshot`]
+    /// * [`Self::create_timer_inert`]
+    pub fn create_timer_repeating<'a, Args>(
+        &self,
+        options: impl IntoTimerOptions<'a>,
+        callback: impl TimerCallRepeating<Args>,
+    ) -> Result<Arc<Timer>, RclrsError> {
+        self.create_timer(options, callback.into_repeating_timer_callback())
+    }
+
+    /// Create a [`Timer`] whose callback will be triggered once after the period
+    /// of the timer has elapsed. After that you will need to use
+    /// [`Timer::set_callback`] or a related method or else nothing will happen
+    /// the following times that the `Timer` elapses.
+    ///
+    /// See also:
+    /// * [`Self::create_timer_repeating`]
+    /// * [`Self::create_time_inert`]
+    pub fn create_timer_oneshot<'a, Args>(
+        &self,
+        options: impl IntoTimerOptions<'a>,
+        callback: impl TimerCallOnce<Args>,
+    ) -> Result<Arc<Timer>, RclrsError> {
+        self.create_timer(options, callback.into_oneshot_timer_callback())
+    }
+
+    /// Create a [`Timer`] without a callback. Nothing will happen when this
+    /// `Timer` elapses until you use [`Timer::set_callback`] or a related method.
+    ///
+    /// See also:
+    /// * [`Self::create_timer_repeating`]
+    /// * [`Self::create_timer_oneshot`]
+    pub fn create_timer_inert<'a>(
+        &self,
+        options: impl IntoTimerOptions<'a>,
+    ) -> Result<Arc<Timer>, RclrsError> {
+        self.create_timer(options, AnyTimerCallback::None)
+    }
+
     /// Returns the subscriptions that have not been dropped yet.
     pub(crate) fn live_subscriptions(&self) -> Vec<Arc<dyn SubscriptionBase>> {
         { self.subscriptions_mtx.lock().unwrap() }
@@ -532,6 +576,8 @@ mod tests {
     use super::*;
     use crate::test_helpers::*;
 
+    use std::time::Duration;
+
     #[test]
     fn traits() {
         assert_send::<Node>();
@@ -585,15 +631,16 @@ mod tests {
 
     #[test]
     fn test_create_timer_without_clock_source() -> Result<(), RclrsError> {
-        let timer_period_ns: i64 = 1e6 as i64; // 1 millisecond.
         let context = Context::new([])?;
-        let dut = NodeBuilder::new(&context, "node_with_timer")
+        let node = NodeBuilder::new(&context, "node_with_timer")
             .namespace("test_create_timer")
             .build()?;
 
-        let _timer =
-            dut.create_timer(timer_period_ns, &context, Some(Box::new(move |_| {})), None)?;
-        assert_eq!(dut.live_timers().len(), 1);
+        let _timer = node.create_timer_repeating(
+            Duration::from_millis(1),
+            || { }
+        )?;
+        assert_eq!(node.live_timers().len(), 1);
 
         Ok(())
     }