Migrate Context, Executor, and Node creation to new API

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

Author: mxgrey

rclrs/src/context.rs

@@ -6,7 +6,7 @@ use std::{
     vec::Vec,
 };
 
-use crate::{rcl_bindings::*, RclrsError, ToResult};
+use crate::{rcl_bindings::*, RclrsError, ToResult, Executor};
 
 /// This is locked whenever initializing or dropping any middleware entity
 /// because we have found issues in RCL and some RMW implementations that
@@ -70,34 +70,41 @@ pub(crate) struct ContextHandle {
     pub(crate) rcl_context: Mutex<rcl_context_t>,
 }
 
+impl Default for Context {
+    fn default() -> Self {
+        // SAFETY: It should always be valid to instantiate a context with no
+        // arguments, no parameters, no options, etc.
+        Self::new([], InitOptions::default())
+        .expect("Failed to instantiate a default context")
+    }
+}
+
 impl Context {
     /// Creates a new context.
     ///
-    /// Usually this would be called with `std::env::args()`, analogously to `rclcpp::init()`.
-    /// See also the official "Passing ROS arguments to nodes via the command-line" tutorial.
+    /// * `args` - A sequence of strings that resembles command line arguments
+    /// that users can pass into a ROS executable. See [the official tutorial][1]
+    /// to know what these arguments may look like. To simply pass in the arguments
+    /// that the user has provided from the command line, call [`Self::from_env`]
+    /// or [`Self::default_from_env`] instead.
     ///
-    /// Creating a context will fail if the args contain invalid ROS arguments.
+    /// * `options` - Additional options that your application can use to override
+    /// settings that would otherwise be determined by the environment.
     ///
-    /// # Example
-    /// ```
-    /// # use rclrs::Context;
-    /// assert!(Context::new([]).is_ok());
-    /// let invalid_remapping = ["--ros-args", "-r", ":=:*/]"].map(String::from);
-    /// assert!(Context::new(invalid_remapping).is_err());
-    /// ```
-    pub fn new(args: impl IntoIterator<Item = String>) -> Result<Self, RclrsError> {
-        Self::new_with_options(args, InitOptions::new())
-    }
-
-    /// Same as [`Context::new`] except you can additionally provide initialization options.
+    /// Creating a context will fail if `args` contains invalid ROS arguments.
     ///
     /// # Example
     /// ```
     /// use rclrs::{Context, InitOptions};
-    /// let context = Context::new_with_options([], InitOptions::new().with_domain_id(Some(5))).unwrap();
+    /// let context = Context::new(
+    ///     std::env::args(),
+    ///     InitOptions::new().with_domain_id(Some(5)),
+    /// ).unwrap();
     /// assert_eq!(context.domain_id(), 5);
-    /// ````
-    pub fn new_with_options(
+    /// ```
+    ///
+    /// [1]: https://docs.ros.org/en/rolling/How-To-Guides/Node-arguments.html
+    pub fn new(
         args: impl IntoIterator<Item = String>,
         options: InitOptions,
     ) -> Result<Self, RclrsError> {
@@ -150,6 +157,23 @@ impl Context {
         })
     }
 
+    /// Same as [`Self::new`] but [`std::env::args`] is automatically passed in
+    /// for `args`.
+    pub fn from_env(options: InitOptions) -> Result<Self, RclrsError> {
+        Self::new(std::env::args(), options)
+    }
+
+    /// Same as [`Self::from_env`] but the default [`InitOptions`] is passed in
+    /// for `options`.
+    pub fn default_from_env() -> Result<Self, RclrsError> {
+        Self::new(std::env::args(), InitOptions::default())
+    }
+
+    /// Create a basic executor that comes built into rclrs.
+    pub fn create_basic_executor(&self) -> Executor {
+        Executor::new(Arc::clone(&self.handle))
+    }
+
     /// Returns the ROS domain ID that the context is using.
     ///
     /// The domain ID controls which nodes can send messages to each other, see the [ROS 2 concept article][1].
@@ -250,14 +274,14 @@ mod tests {
     #[test]
     fn test_create_context() -> Result<(), RclrsError> {
         // If the context fails to be created, this will cause a panic
-        let _ = Context::new(vec![])?;
+        let _ = Context::new(vec![], InitOptions::default())?;
         Ok(())
     }
 
     #[test]
     fn test_context_ok() -> Result<(), RclrsError> {
         // If the context fails to be created, this will cause a panic
-        let created_context = Context::new(vec![]).unwrap();
+        let created_context = Context::new(vec![], InitOptions::default()).unwrap();
         assert!(created_context.ok());
 
         Ok(())

rclrs/src/error.rs

@@ -352,3 +352,24 @@ impl ToResult for rcl_ret_t {
         to_rclrs_result(*self)
     }
 }
+
+/// A helper trait to disregard timeouts as not an error.
+pub trait RclrsErrorFilter {
+    /// If the result was a timeout error, change it to `Ok(())`.
+    fn timeout_ok(self) -> Result<(), RclrsError>;
+}
+
+impl RclrsErrorFilter for Result<(), RclrsError> {
+    fn timeout_ok(self) -> Result<(), RclrsError> {
+        match self {
+            Ok(()) => Ok(()),
+            Err(err) => {
+                if matches!(err, RclrsError::RclError { code: RclReturnCode::Timeout, .. }) {
+                    return Ok(());
+                }
+
+                Err(err)
+            }
+        }
+    }
+}

rclrs/src/executor.rs

@@ -1,48 +1,61 @@
-use crate::{rcl_bindings::rcl_context_is_valid, Node, RclReturnCode, RclrsError, WaitSet};
+use crate::{
+    rcl_bindings::rcl_context_is_valid,
+    Node, RclrsError, WaitSet, ContextHandle, NodeOptions, WeakNode,
+};
 use std::{
-    sync::{Arc, Mutex, Weak},
+    sync::{Arc, Mutex},
     time::Duration,
 };
 
 /// Single-threaded executor implementation.
-pub struct SingleThreadedExecutor {
-    nodes_mtx: Mutex<Vec<Weak<Node>>>,
+pub struct Executor {
+    context: Arc<ContextHandle>,
+    nodes_mtx: Mutex<Vec<WeakNode>>,
 }
 
-impl Default for SingleThreadedExecutor {
-    fn default() -> Self {
-        Self::new()
+impl Executor {
+    /// Create a [`Node`] that will run on this Executor.
+    pub fn create_node(
+        &self,
+        options: impl Into<NodeOptions>,
+    ) -> Result<Node, RclrsError> {
+        let options: NodeOptions = options.into();
+        let node = options.build(&self.context)?;
+        self.nodes_mtx.lock().unwrap().push(node.downgrade());
+        Ok(node)
     }
-}
 
-impl SingleThreadedExecutor {
-    /// Creates a new executor.
-    pub fn new() -> Self {
-        SingleThreadedExecutor {
-            nodes_mtx: Mutex::new(Vec::new()),
-        }
-    }
+    /// Spin the Executor. The current thread will be blocked until the Executor
+    /// stops spinning.
+    ///
+    /// [`SpinOptions`] can be used to automatically stop the spinning when
+    /// certain conditions are met. Use `SpinOptions::default()` to allow the
+    /// Executor to keep spinning indefinitely.
+    pub fn spin(&mut self, options: SpinOptions) -> Result<(), RclrsError> {
+        loop {
+            if self.nodes_mtx.lock().unwrap().is_empty() {
+                // Nothing to spin for, so just quit here
+                return Ok(());
+            }
 
-    /// Add a node to the executor.
-    pub fn add_node(&self, node: &Arc<Node>) -> Result<(), RclrsError> {
-        { self.nodes_mtx.lock().unwrap() }.push(Arc::downgrade(node));
-        Ok(())
-    }
+            self.spin_once(options.timeout)?;
 
-    /// Remove a node from the executor.
-    pub fn remove_node(&self, node: Arc<Node>) -> Result<(), RclrsError> {
-        { self.nodes_mtx.lock().unwrap() }
-            .retain(|n| !n.upgrade().map(|n| Arc::ptr_eq(&n, &node)).unwrap_or(false));
-        Ok(())
+            if options.only_next_available_work {
+                // We were only suppposed to spin once, so quit here
+                return Ok(());
+            }
+
+            std::thread::yield_now();
+        }
     }
 
     /// Polls the nodes for new messages and executes the corresponding callbacks.
     ///
     /// This function additionally checks that the context is still valid.
-    pub fn spin_once(&self, timeout: Option<Duration>) -> Result<(), RclrsError> {
+    fn spin_once(&self, timeout: Option<Duration>) -> Result<(), RclrsError> {
         for node in { self.nodes_mtx.lock().unwrap() }
             .iter()
-            .filter_map(Weak::upgrade)
+            .filter_map(WeakNode::upgrade)
             .filter(|node| unsafe {
                 rcl_context_is_valid(&*node.handle.context_handle.rcl_context.lock().unwrap())
             })
@@ -66,19 +79,51 @@ impl SingleThreadedExecutor {
         Ok(())
     }
 
-    /// Convenience function for calling [`SingleThreadedExecutor::spin_once`] in a loop.
-    pub fn spin(&self) -> Result<(), RclrsError> {
-        while !{ self.nodes_mtx.lock().unwrap() }.is_empty() {
-            match self.spin_once(None) {
-                Ok(_)
-                | Err(RclrsError::RclError {
-                    code: RclReturnCode::Timeout,
-                    ..
-                }) => std::thread::yield_now(),
-                error => return error,
-            }
+    /// Used by [`Context`] to create the `Executor`. Users cannot call this
+    /// function.
+    pub(crate) fn new(context: Arc<ContextHandle>) -> Self {
+        Self {
+            context,
+            nodes_mtx: Mutex::new(Vec::new()),
         }
+    }
+}
 
-        Ok(())
+/// A bundle of optional conditions that a user may want to impose on how long
+/// an executor spins for.
+///
+/// By default the executor will be allowed to spin indefinitely.
+#[non_exhaustive]
+#[derive(Default)]
+pub struct SpinOptions {
+    /// Only perform the next available work. This is similar to spin_once in
+    /// rclcpp and rclpy.
+    ///
+    /// To only process work that is immediately available without waiting at all,
+    /// set a timeout of zero.
+    pub only_next_available_work: bool,
+    /// Stop waiting after this duration of time has passed. Use `Some(0)` to not
+    /// wait any amount of time. Use `None` to wait an infinite amount of time.
+    pub timeout: Option<Duration>,
+}
+
+impl SpinOptions {
+    /// Use default spin options.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Behave like spin_once in rclcpp and rclpy.
+    pub fn spin_once() -> Self {
+        Self {
+            only_next_available_work: true,
+            ..Default::default()
+        }
+    }
+
+    /// Stop spinning once this durtion of time is reached.
+    pub fn timeout(mut self, timeout: Duration) -> Self {
+        self.timeout = Some(timeout);
+        self
     }
 }

rclrs/src/lib.rs

@@ -30,8 +30,6 @@ mod rcl_bindings;
 #[cfg(feature = "dyn_msg")]
 pub mod dynamic_message;
 
-use std::{sync::Arc, time::Duration};
-
 pub use arguments::*;
 pub use client::*;
 pub use clock::*;
@@ -48,66 +46,3 @@ pub use subscription::*;
 pub use time::*;
 use time_source::*;
 pub use wait::*;
-
-/// Polls the node for new messages and executes the corresponding callbacks.
-///
-/// See [`WaitSet::wait`] for the meaning of the `timeout` parameter.
-///
-/// This may under some circumstances return
-/// [`SubscriptionTakeFailed`][1], [`ClientTakeFailed`][1], [`ServiceTakeFailed`][1] when the wait
-/// set spuriously wakes up.
-/// This can usually be ignored.
-///
-/// [1]: crate::RclReturnCode
-pub fn spin_once(node: Arc<Node>, timeout: Option<Duration>) -> Result<(), RclrsError> {
-    let executor = SingleThreadedExecutor::new();
-    executor.add_node(&node)?;
-    executor.spin_once(timeout)
-}
-
-/// Convenience function for calling [`spin_once`] in a loop.
-pub fn spin(node: Arc<Node>) -> Result<(), RclrsError> {
-    let executor = SingleThreadedExecutor::new();
-    executor.add_node(&node)?;
-    executor.spin()
-}
-
-/// Creates a new node in the empty namespace.
-///
-/// Convenience function equivalent to [`Node::new`][1].
-/// Please see that function's documentation.
-///
-/// [1]: crate::Node::new
-///
-/// # Example
-/// ```
-/// # use rclrs::{Context, RclrsError};
-/// let ctx = Context::new([])?;
-/// let node = rclrs::create_node(&ctx, "my_node");
-/// assert!(node.is_ok());
-/// # Ok::<(), RclrsError>(())
-/// ```
-pub fn create_node(context: &Context, node_name: &str) -> Result<Arc<Node>, RclrsError> {
-    Node::new(context, node_name)
-}
-
-/// Creates a [`NodeBuilder`].
-///
-/// Convenience function equivalent to [`NodeBuilder::new()`][1] and [`Node::builder()`][2].
-/// Please see that function's documentation.
-///
-/// [1]: crate::NodeBuilder::new
-/// [2]: crate::Node::builder
-///
-/// # Example
-/// ```
-/// # use rclrs::{Context, RclrsError};
-/// let context = Context::new([])?;
-/// let node_builder = rclrs::create_node_builder(&context, "my_node");
-/// let node = node_builder.build()?;
-/// assert_eq!(node.name(), "my_node");
-/// # Ok::<(), RclrsError>(())
-/// ```
-pub fn create_node_builder(context: &Context, node_name: &str) -> NodeBuilder {
-    Node::builder(context, node_name)
-}