Add context builder

rclrs/build.rs

@@ -36,6 +36,10 @@ fn main() {
         .allowlist_var("rmw_.*")
         .allowlist_var("rcutils_.*")
         .allowlist_var("rosidl_.*")
+        .blocklist_function("rcl_take_dynamic_.*")
+        .blocklist_function("rmw_take_dynamic_.*")
+        .blocklist_function("rmw_serialization_support_init")
+        .blocklist_function("rosidl_dynamic_.*")
         .layout_tests(false)
         .size_t_is_usize(true)
         .default_enum_style(bindgen::EnumVariation::Rust {

rclrs/src/context.rs

@@ -1,11 +1,10 @@
-use std::ffi::CString;
-use std::os::raw::c_char;
+mod builder;
 use std::string::String;
 use std::sync::{Arc, Mutex};
-use std::vec::Vec;
 
+pub use self::builder::*;
 use crate::rcl_bindings::*;
-use crate::{RclrsError, ToResult};
+use crate::RclrsError;
 
 impl Drop for rcl_context_t {
     fn drop(&mut self) {
@@ -43,64 +42,10 @@ pub struct 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.
-    ///
-    /// Creating a context can fail in case the args contain invalid ROS arguments.
-    ///
-    /// # 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());
-    /// ```
+    /// See [`ContextBuilder::new()`] for documentation.
+    #[allow(clippy::new_ret_no_self)]
     pub fn new(args: impl IntoIterator<Item = String>) -> Result<Self, RclrsError> {
-        // SAFETY: Getting a zero-initialized value is always safe
-        let mut rcl_context = unsafe { rcl_get_zero_initialized_context() };
-        let cstring_args: Vec<CString> = args
-            .into_iter()
-            .map(|arg| {
-                CString::new(arg.as_str()).map_err(|err| RclrsError::StringContainsNul {
-                    err,
-                    s: arg.clone(),
-                })
-            })
-            .collect::<Result<_, _>>()?;
-        // Vector of pointers into cstring_args
-        let c_args: Vec<*const c_char> = cstring_args.iter().map(|arg| arg.as_ptr()).collect();
-        unsafe {
-            // SAFETY: No preconditions for this function.
-            let allocator = rcutils_get_default_allocator();
-            // SAFETY: Getting a zero-initialized value is always safe.
-            let mut rcl_init_options = rcl_get_zero_initialized_init_options();
-            // SAFETY: Passing in a zero-initialized value is expected.
-            // In the case where this returns not ok, there's nothing to clean up.
-            rcl_init_options_init(&mut rcl_init_options, allocator).ok()?;
-            // SAFETY: This function does not store the ephemeral init_options and c_args
-            // pointers. Passing in a zero-initialized rcl_context is expected.
-            let ret = rcl_init(
-                c_args.len() as i32,
-                if c_args.is_empty() {
-                    std::ptr::null()
-                } else {
-                    c_args.as_ptr()
-                },
-                &rcl_init_options,
-                &mut rcl_context,
-            )
-            .ok();
-            // SAFETY: It's safe to pass in an initialized object.
-            // Early return will not leak memory, because this is the last fini function.
-            rcl_init_options_fini(&mut rcl_init_options).ok()?;
-            // Move the check after the last fini()
-            ret?;
-        }
-        Ok(Self {
-            rcl_context_mtx: Arc::new(Mutex::new(rcl_context)),
-        })
+        Self::builder(args).build()
     }
 
     /// Checks if the context is still valid.
@@ -114,6 +59,65 @@ impl Context {
         // SAFETY: No preconditions for this function.
         unsafe { rcl_context_is_valid(rcl_context) }
     }
+
+    /// Returns the context domain id.
+    ///
+    /// The domain ID controls which nodes can send messages to each other, see the [ROS 2 concept article][1].
+    /// It can be set through the `ROS_DOMAIN_ID` environment variable
+    /// or [`ContextBuilder`][2]
+    ///
+    /// [1]: https://docs.ros.org/en/rolling/Concepts/About-Domain-ID.html
+    /// [2]: crate::ContextBuilder
+    ///
+    /// # Example
+    /// ```
+    /// # use rclrs::{Context, RclrsError};
+    /// // Set default ROS domain ID to 10 here
+    /// std::env::set_var("ROS_DOMAIN_ID", "10");
+    /// let context = Context::new([])?;
+    /// let domain_id = context.domain_id();
+    /// assert_eq!(domain_id, 10);
+    /// let context = Context::builder([]).domain_id(11).build()?;
+    /// let domain_id = context.domain_id();
+    /// assert_eq!(domain_id, 11);
+    /// # Ok::<(), RclrsError>(())
+    /// ```
+    pub fn domain_id(&self) -> usize {
+        let mut domain_id: usize = 0;
+
+        #[cfg(not(ros_distro = "foxy"))]
+        let ret = unsafe {
+            let mut rcl_context = self.rcl_context_mtx.lock().unwrap();
+            // SAFETY: No preconditions for this function.
+            rcl_context_get_domain_id(&mut *rcl_context, &mut domain_id)
+        };
+        #[cfg(ros_distro = "foxy")]
+        let ret = unsafe {
+            // SAFETY: Getting the default domain ID, based on the environment
+            rcl_get_default_domain_id(&mut domain_id)
+        };
+
+        debug_assert_eq!(ret, 0);
+        domain_id
+    }
+
+    /// Creates a [`ContextBuilder`][1] with the given name.
+    ///
+    /// Convenience function equivalent to [`ContextBuilder::new()`][2].
+    ///
+    /// [1]: crate::ContextBuilder
+    /// [2]: crate::ContextBuilder::new
+    ///
+    /// # Example
+    /// ```
+    /// # use rclrs::{Context, RclrsError};
+    /// let context_builder = Context::builder([]);
+    /// assert!(context_builder.build().is_ok());
+    /// # Ok::<(), RclrsError>(())
+    /// ```
+    pub fn builder(args: impl IntoIterator<Item = String>) -> ContextBuilder {
+        ContextBuilder::new(args)
+    }
 }
 
 #[cfg(test)]

rclrs/src/context/builder.rs

@@ -0,0 +1,148 @@
+use std::ffi::CString;
+use std::os::raw::c_char;
+use std::sync::{Arc, Mutex};
+
+use crate::rcl_bindings::*;
+use crate::{Context, RclrsError, ToResult};
+
+/// A builder for creating a [`Context`][1].
+///
+/// The builder pattern allows selectively setting some fields, and leaving all others at their default values.
+/// This struct instance can be created via [`Context::builder()`][2].
+///
+/// # Example
+/// ```
+/// # use rclrs::{Context, ContextBuilder, RclrsError};
+/// // Building a context in a single expression
+/// let args = ["ROS 1 ROS 2"].map(String::from);
+/// let context = ContextBuilder::new(args.clone()).domain_id(1).build()?;
+/// assert_eq!(context.domain_id(), 1);
+/// // Building a context via Context::builder()
+/// let context = Context::builder(args.clone()).domain_id(2).build()?;
+/// assert_eq!(context.domain_id(), 2);
+/// // Building a context step-by-step
+/// let mut builder = Context::builder(args.clone());
+/// builder = builder.domain_id(3);
+/// let context = builder.build()?;
+/// assert_eq!(context.domain_id(), 3);
+/// # Ok::<(), RclrsError>(())
+/// ```
+///
+/// [1]: crate::Context
+/// [2]: crate::Context::builder
+pub struct ContextBuilder {
+    arguments: Vec<String>,
+    domain_id: usize,
+}
+
+impl ContextBuilder {
+    /// Creates a builder for a context with arguments.
+    ///
+    /// 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.
+    ///
+    /// Creating a context can fail in case the args contain invalid ROS arguments.
+    ///
+    /// # Example
+    /// ```
+    /// # use rclrs::ContextBuilder;
+    /// let invalid_remapping = ["--ros-args", "-r", ":=:*/]"].map(String::from);
+    /// assert!(ContextBuilder::new(invalid_remapping).build().is_err());
+    /// let valid_remapping = ["--ros-args", "--remap", "__node:=my_node"].map(String::from);
+    /// assert!(ContextBuilder::new(valid_remapping).build().is_ok());
+    /// ```
+    pub fn new(args: impl IntoIterator<Item = String>) -> ContextBuilder {
+        let mut domain_id = 0;
+        // SAFETY: Getting the default domain ID, based on the environment
+        let ret = unsafe { rcl_get_default_domain_id(&mut domain_id) };
+        debug_assert_eq!(ret, 0);
+
+        ContextBuilder {
+            arguments: args.into_iter().collect(),
+            domain_id,
+        }
+    }
+
+    /// Sets the context domain id.
+    ///
+    /// The domain ID controls which nodes can send messages to each other, see the [ROS 2 concept article][1].
+    ///
+    /// [1]: https://docs.ros.org/en/rolling/Concepts/About-Domain-ID.html
+    pub fn domain_id(mut self, domain_id: usize) -> Self {
+        #[cfg(ros_distro = "foxy")]
+        std::env::set_var("ROS_DOMAIN_ID", domain_id.to_string());
+
+        self.domain_id = domain_id;
+        self
+    }
+
+    /// Builds the context instance and `rcl_init_options` in order to initialize rcl
+    ///
+    /// For example usage, see the [`ContextBuilder`][1] docs.
+    ///
+    /// [1]: crate::ContextBuilder
+    pub fn build(&self) -> Result<Context, RclrsError> {
+        // SAFETY: Getting a zero-initialized value is always safe
+        let mut rcl_context = unsafe { rcl_get_zero_initialized_context() };
+        let cstring_args: Vec<CString> = self
+            .arguments
+            .iter()
+            .map(|arg| {
+                CString::new(arg.as_str()).map_err(|err| RclrsError::StringContainsNul {
+                    err,
+                    s: arg.clone(),
+                })
+            })
+            .collect::<Result<_, _>>()?;
+        // Vector of pointers into cstring_args
+        let c_args: Vec<*const c_char> = cstring_args.iter().map(|arg| arg.as_ptr()).collect();
+        let rcl_init_options = self.create_rcl_init_options()?;
+        unsafe {
+            // SAFETY: This function does not store the ephemeral init_options and c_args
+            // pointers. Passing in a zero-initialized rcl_context is expected.
+            rcl_init(
+                c_args.len() as i32,
+                if c_args.is_empty() {
+                    std::ptr::null()
+                } else {
+                    c_args.as_ptr()
+                },
+                &rcl_init_options,
+                &mut rcl_context,
+            )
+            .ok()?;
+        }
+        Ok(Context {
+            rcl_context_mtx: Arc::new(Mutex::new(rcl_context)),
+        })
+    }
+
+    /// Creates a rcl_init_options_t struct from this builder.
+    ///
+    /// domain id validation is performed in this method.
+    fn create_rcl_init_options(&self) -> Result<rcl_init_options_t, RclrsError> {
+        unsafe {
+            // SAFETY: No preconditions for this function.
+            let allocator = rcutils_get_default_allocator();
+            // SAFETY: Getting a zero-initialized value is always safe.
+            let mut rcl_init_options = rcl_get_zero_initialized_init_options();
+            // SAFETY: Passing in a zero-initialized value is expected.
+            // In the case where this returns not ok, there's nothing to clean up.
+            rcl_init_options_init(&mut rcl_init_options, allocator).ok()?;
+            // SAFETY: Setting domain id in the init options provided.
+            // In the case where this returns not ok, the domain id is invalid.
+            rcl_init_options_set_domain_id(&mut rcl_init_options, self.domain_id).ok()?;
+
+            Ok(rcl_init_options)
+        }
+    }
+}
+
+impl Drop for rcl_init_options_t {
+    fn drop(&mut self) {
+        // SAFETY: Do not finish this struct except here.
+        unsafe {
+            rcl_init_options_fini(self).ok().unwrap();
+        }
+    }
+}

rclrs/src/dynamic_message.rs

@@ -75,7 +75,7 @@ fn get_type_support_library(
     let ament = ament_rs::Ament::new().map_err(|_| RequiredPrefixNotSourced {
         package: package_name.to_owned(),
     })?;
-    let prefix = PathBuf::from(ament.find_package(&package_name).ok_or(
+    let prefix = PathBuf::from(ament.find_package(package_name).ok_or(
         RequiredPrefixNotSourced {
             package: package_name.to_owned(),
         },

rclrs/src/error.rs

@@ -347,6 +347,6 @@ pub(crate) trait ToResult {
 
 impl ToResult for rcl_ret_t {
     fn ok(&self) -> Result<(), RclrsError> {
-        to_rclrs_result(*self as i32)
+        to_rclrs_result(*self)
     }
 }

rclrs/src/node.rs

@@ -173,7 +173,7 @@ impl Node {
         &self,
         getter: unsafe extern "C" fn(*const rcl_node_t) -> *const c_char,
     ) -> String {
-        unsafe { call_string_getter_with_handle(&*self.rcl_node_mtx.lock().unwrap(), getter) }
+        unsafe { call_string_getter_with_handle(&self.rcl_node_mtx.lock().unwrap(), getter) }
     }
 
     /// Creates a [`Client`][1].
@@ -317,7 +317,7 @@ impl Node {
     }
 
     /// Returns the ROS domain ID that the node is using.
-    ///    
+    ///
     /// The domain ID controls which nodes can send messages to each other, see the [ROS 2 concept article][1].
     /// It can be set through the `ROS_DOMAIN_ID` environment variable.
     ///

rclrs/src/parameter/value.rs

@@ -163,8 +163,8 @@ mod tests {
             assert!(!rcl_params.is_null());
             assert_eq!(unsafe { (*rcl_params).num_nodes }, 1);
             let rcl_node_params = unsafe { &(*(*rcl_params).params) };
-            assert_eq!((*rcl_node_params).num_params, 1);
-            let rcl_variant = unsafe { &(*(*rcl_node_params).parameter_values) };
+            assert_eq!(rcl_node_params.num_params, 1);
+            let rcl_variant = unsafe { &(*rcl_node_params.parameter_values) };
             let param_value = unsafe { ParameterValue::from_rcl_variant(rcl_variant) };
             assert_eq!(param_value, pair.1);
             unsafe { rcl_yaml_node_struct_fini(rcl_params) };

rclrs/src/subscription.rs

@@ -183,7 +183,7 @@ where
     ///
     /// This can be more efficient for messages containing large arrays.
     pub fn take_boxed(&self) -> Result<(Box<T>, MessageInfo), RclrsError> {
-        let mut rmw_message = Box::new(<T as Message>::RmwMsg::default());
+        let mut rmw_message = Box::<<T as Message>::RmwMsg>::default();
         let message_info = self.take_inner(&mut *rmw_message)?;
         // TODO: This will still use the stack in general. Change signature of
         // from_rmw_message to allow placing the result in a Box directly.