Use option struct for create_action_{client,server} arguments

nwn · nwn · commit 8973176fc61f · 2025-06-07T20:39:20.000-04:00
This works similarly to the option struct used for the other endpoint
types, except that it cannot use the PrimitiveOptions stuff since
actions have multiple different QoS settings.
diff --git a/rclrs/src/action.rs b/rclrs/src/action.rs
@@ -5,8 +5,8 @@ mod server_goal_handle;
 use crate::rcl_bindings::RCL_ACTION_UUID_SIZE;
 use std::fmt;
 
-pub use client::{ActionClient, ActionClientBase, ActionClientState};
-pub use server::{ActionServer, ActionServerBase, ActionServerState};
+pub use client::{ActionClient, ActionClientBase, ActionClientOptions, ActionClientState};
+pub use server::{ActionServer, ActionServerBase, ActionServerOptions, ActionServerState};
 pub use server_goal_handle::ServerGoalHandle;
 
 /// A unique identifier for a goal request.
diff --git a/rclrs/src/action/client.rs b/rclrs/src/action/client.rs
@@ -1,8 +1,9 @@
 use crate::{
-    error::ToResult, rcl_bindings::*, wait::WaitableNumEntities, Node, NodeHandle, RclrsError,
-    ENTITY_LIFECYCLE_MUTEX,
+    error::ToResult, rcl_bindings::*, wait::WaitableNumEntities, Node, NodeHandle, QoSProfile,
+    RclrsError, ENTITY_LIFECYCLE_MUTEX,
 };
 use std::{
+    borrow::Borrow,
     ffi::CString,
     marker::PhantomData,
     sync::{atomic::AtomicBool, Arc, Mutex, MutexGuard},
@@ -101,17 +102,22 @@ where
     T: rosidl_runtime_rs::Action,
 {
     /// Creates a new action client.
-    pub(crate) fn new(node: &Node, topic: &str) -> Result<Self, RclrsError>
+    pub(crate) fn new<'a>(
+        node: &Node,
+        options: impl Into<ActionClientOptions<'a>>,
+    ) -> Result<Self, RclrsError>
     where
         T: rosidl_runtime_rs::Action,
     {
+        let options = options.into();
         // SAFETY: Getting a zero-initialized value is always safe.
         let mut rcl_action_client = unsafe { rcl_action_get_zero_initialized_client() };
         let type_support = T::get_type_support() as *const rosidl_action_type_support_t;
-        let topic_c_string = CString::new(topic).map_err(|err| RclrsError::StringContainsNul {
-            err,
-            s: topic.into(),
-        })?;
+        let action_name_c_string =
+            CString::new(options.action_name).map_err(|err| RclrsError::StringContainsNul {
+                err,
+                s: options.action_name.into(),
+            })?;
 
         // SAFETY: No preconditions for this function.
         let action_client_options = unsafe { rcl_action_client_get_default_options() };
@@ -123,7 +129,7 @@ where
             // SAFETY:
             // * The rcl_action_client was zero-initialized as expected by this function.
             // * The rcl_node is kept alive by the NodeHandle because it is a dependency of the action client.
-            // * The topic name and the options are copied by this function, so they can be dropped
+            // * The action name and the options are copied by this function, so they can be dropped
             //   afterwards.
             // * The entity lifecycle mutex is locked to protect against the risk of global
             //   variables in the rmw implementation being unsafely modified during initialization.
@@ -132,7 +138,7 @@ where
                     &mut rcl_action_client,
                     &mut *rcl_node,
                     type_support,
-                    topic_c_string.as_ptr(),
+                    action_name_c_string.as_ptr(),
                     &action_client_options,
                 )
                 .ok()?;
@@ -209,3 +215,44 @@ where
         }
     }
 }
+
+/// `ActionClientOptions` are used by [`Node::create_action_client`][1] to initialize an
+/// [`ActionClient`].
+///
+/// [1]: crate::Node::create_action_client
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub struct ActionClientOptions<'a> {
+    /// The name of the action that this client will send requests to
+    pub action_name: &'a str,
+    /// The quality of service profile for the goal service
+    pub goal_service_qos: QoSProfile,
+    /// The quality of service profile for the result service
+    pub result_service_qos: QoSProfile,
+    /// The quality of service profile for the cancel service
+    pub cancel_service_qos: QoSProfile,
+    /// The quality of service profile for the feedback topic
+    pub feedback_topic_qos: QoSProfile,
+    /// The quality of service profile for the status topic
+    pub status_topic_qos: QoSProfile,
+}
+
+impl<'a> ActionClientOptions<'a> {
+    /// Initialize a new [`ActionClientOptions`] with default settings.
+    pub fn new(action_name: &'a str) -> Self {
+        Self {
+            action_name,
+            goal_service_qos: QoSProfile::services_default(),
+            result_service_qos: QoSProfile::services_default(),
+            cancel_service_qos: QoSProfile::services_default(),
+            feedback_topic_qos: QoSProfile::topics_default(),
+            status_topic_qos: QoSProfile::action_status_default(),
+        }
+    }
+}
+
+impl<'a, T: Borrow<str> + ?Sized + 'a> From<&'a T> for ActionClientOptions<'a> {
+    fn from(value: &'a T) -> Self {
+        Self::new(value.borrow())
+    }
+}
diff --git a/rclrs/src/action/server.rs b/rclrs/src/action/server.rs
@@ -3,10 +3,11 @@ use crate::{
     error::{RclReturnCode, ToResult},
     rcl_bindings::*,
     wait::WaitableNumEntities,
-    Clock, DropGuard, Node, NodeHandle, RclrsError, ENTITY_LIFECYCLE_MUTEX,
+    Clock, DropGuard, Node, NodeHandle, QoSProfile, RclrsError, ENTITY_LIFECYCLE_MUTEX,
 };
 use rosidl_runtime_rs::{Action, ActionImpl, Message, Service};
 use std::{
+    borrow::Borrow,
     collections::HashMap,
     ffi::CString,
     sync::{atomic::AtomicBool, Arc, Mutex, MutexGuard},
@@ -120,23 +121,25 @@ where
     T: rosidl_runtime_rs::Action + rosidl_runtime_rs::ActionImpl,
 {
     /// Creates a new action server.
-    pub(crate) fn new(
+    pub(crate) fn new<'a>(
         node: &Node,
-        topic: &str,
+        options: impl Into<ActionServerOptions<'a>>,
         goal_callback: impl Fn(GoalUuid, T::Goal) -> GoalResponse + 'static + Send + Sync,
         cancel_callback: impl Fn(Arc<ServerGoalHandle<T>>) -> CancelResponse + 'static + Send + Sync,
         accepted_callback: impl Fn(Arc<ServerGoalHandle<T>>) + 'static + Send + Sync,
     ) -> Result<Self, RclrsError>
     where
         T: rosidl_runtime_rs::Action + rosidl_runtime_rs::ActionImpl,
     {
+        let options = options.into();
         // SAFETY: Getting a zero-initialized value is always safe.
         let mut rcl_action_server = unsafe { rcl_action_get_zero_initialized_server() };
         let type_support = T::get_type_support() as *const rosidl_action_type_support_t;
-        let topic_c_string = CString::new(topic).map_err(|err| RclrsError::StringContainsNul {
-            err,
-            s: topic.into(),
-        })?;
+        let action_name_c_string =
+            CString::new(options.action_name).map_err(|err| RclrsError::StringContainsNul {
+                err,
+                s: options.action_name.into(),
+            })?;
 
         // SAFETY: No preconditions for this function.
         let action_server_options = unsafe { rcl_action_server_get_default_options() };
@@ -151,7 +154,7 @@ where
             // SAFETY:
             // * The rcl_action_server is zero-initialized as mandated by this function.
             // * The rcl_node is kept alive by the NodeHandle because it is a dependency of the action server.
-            // * The topic name and the options are copied by this function, so they can be dropped
+            // * The action name and the options are copied by this function, so they can be dropped
             //   afterwards.
             // * The entity lifecycle mutex is locked to protect against the risk of global
             //   variables in the rmw implementation being unsafely modified during initialization.
@@ -161,7 +164,7 @@ where
                     &mut *rcl_node,
                     &mut *rcl_clock,
                     type_support,
-                    topic_c_string.as_ptr(),
+                    action_name_c_string.as_ptr(),
                     &action_server_options,
                 )
                 .ok()?;
@@ -736,3 +739,45 @@ where
         }
     }
 }
+
+/// `ActionServerOptions` are used by [`Node::create_action_server`][1] to initialize an
+/// [`ActionServer`].
+///
+/// [1]: crate::Node::create_action_server
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub struct ActionServerOptions<'a> {
+    /// The name of the action implemented by this server
+    pub action_name: &'a str,
+    /// The quality of service profile for the goal service
+    pub goal_service_qos: QoSProfile,
+    /// The quality of service profile for the result service
+    pub result_service_qos: QoSProfile,
+    /// The quality of service profile for the cancel service
+    pub cancel_service_qos: QoSProfile,
+    /// The quality of service profile for the feedback topic
+    pub feedback_topic_qos: QoSProfile,
+    /// The quality of service profile for the status topic
+    pub status_topic_qos: QoSProfile,
+    // TODO(nwn): result_timeout
+}
+
+impl<'a> ActionServerOptions<'a> {
+    /// Initialize a new [`ActionServerOptions`] with default settings.
+    pub fn new(action_name: &'a str) -> Self {
+        Self {
+            action_name,
+            goal_service_qos: QoSProfile::services_default(),
+            result_service_qos: QoSProfile::services_default(),
+            cancel_service_qos: QoSProfile::services_default(),
+            feedback_topic_qos: QoSProfile::topics_default(),
+            status_topic_qos: QoSProfile::action_status_default(),
+        }
+    }
+}
+
+impl<'a, T: Borrow<str> + ?Sized + 'a> From<&'a T> for ActionServerOptions<'a> {
+    fn from(value: &'a T) -> Self {
+        Self::new(value.borrow())
+    }
+}
diff --git a/rclrs/src/node.rs b/rclrs/src/node.rs
@@ -19,13 +19,14 @@ use std::{
 use rosidl_runtime_rs::Message;
 
 use crate::{
-    rcl_bindings::*, ActionClient, ActionClientBase, ActionClientState, ActionServer,
-    ActionServerBase, ActionServerState, CancelResponse, Client, ClientBase, ClientOptions,
-    ClientState, Clock, ContextHandle, GoalResponse, GoalUuid, GuardCondition, LogParams, Logger,
-    ParameterBuilder, ParameterInterface, ParameterVariant, Parameters, Publisher,
-    PublisherOptions, PublisherState, RclrsError, ServerGoalHandle, Service, ServiceBase,
-    ServiceOptions, ServiceState, Subscription, SubscriptionBase, SubscriptionCallback,
-    SubscriptionOptions, SubscriptionState, TimeSource, ToLogParams, ENTITY_LIFECYCLE_MUTEX,
+    rcl_bindings::*, ActionClient, ActionClientBase, ActionClientOptions, ActionClientState,
+    ActionServer, ActionServerBase, ActionServerOptions, ActionServerState, CancelResponse, Client,
+    ClientBase, ClientOptions, ClientState, Clock, ContextHandle, GoalResponse, GoalUuid,
+    GuardCondition, LogParams, Logger, ParameterBuilder, ParameterInterface, ParameterVariant,
+    Parameters, Publisher, PublisherOptions, PublisherState, RclrsError, ServerGoalHandle, Service,
+    ServiceBase, ServiceOptions, ServiceState, Subscription, SubscriptionBase,
+    SubscriptionCallback, SubscriptionOptions, SubscriptionState, TimeSource, ToLogParams,
+    ENTITY_LIFECYCLE_MUTEX,
 };
 
 // SAFETY: The functions accessing this type, including drop(), shouldn't care about the thread
@@ -296,14 +297,14 @@ impl NodeState {
     ///
     /// [1]: crate::ActionClient
     // TODO: make action client's lifetime depend on node's lifetime
-    pub fn create_action_client<T>(
+    pub fn create_action_client<'a, T>(
         self: &Arc<Self>,
-        topic: &str,
+        options: impl Into<ActionClientOptions<'a>>,
     ) -> Result<ActionClient<T>, RclrsError>
     where
         T: rosidl_runtime_rs::Action,
     {
-        let action_client = Arc::new(ActionClientState::<T>::new(self, topic)?);
+        let action_client = Arc::new(ActionClientState::<T>::new(self, options)?);
         self.action_clients_mtx
             .lock()
             .unwrap()
@@ -315,9 +316,9 @@ impl NodeState {
     ///
     /// [1]: crate::ActionServer
     // TODO: make action server's lifetime depend on node's lifetime
-    pub fn create_action_server<ActionT, GoalCallback, CancelCallback, AcceptedCallback>(
+    pub fn create_action_server<'a, ActionT, GoalCallback, CancelCallback, AcceptedCallback>(
         self: &Arc<Self>,
-        topic: &str,
+        options: impl Into<ActionServerOptions<'a>>,
         handle_goal: GoalCallback,
         handle_cancel: CancelCallback,
         handle_accepted: AcceptedCallback,
@@ -330,7 +331,7 @@ impl NodeState {
     {
         let action_server = Arc::new(ActionServerState::<ActionT>::new(
             self,
-            topic,
+            options,
             handle_goal,
             handle_cancel,
             handle_accepted,
diff --git a/rclrs/src/qos.rs b/rclrs/src/qos.rs
@@ -295,6 +295,11 @@ impl QoSProfile {
     pub fn system_default() -> Self {
         QOS_PROFILE_SYSTEM_DEFAULT
     }
+
+    /// Get the default QoS profile for action status topics.
+    pub fn action_status_default() -> Self {
+        QOS_PROFILE_ACTION_STATUS_DEFAULT
+    }
 }
 
 impl From<QoSHistoryPolicy> for rmw_qos_history_policy_t {
@@ -478,3 +483,17 @@ pub const QOS_PROFILE_SYSTEM_DEFAULT: QoSProfile = QoSProfile {
     liveliness_lease: QoSDuration::SystemDefault,
     avoid_ros_namespace_conventions: false,
 };
+
+/// Equivalent to `rcl_action_qos_profile_status_default` from the [`rcl_action` package][1].
+///
+/// [1]: https://github.com/ros2/rcl/blob/rolling/rcl_action/include/rcl_action/default_qos.h
+pub const QOS_PROFILE_ACTION_STATUS_DEFAULT: QoSProfile = QoSProfile {
+    history: QoSHistoryPolicy::KeepLast { depth: 1 },
+    reliability: QoSReliabilityPolicy::Reliable,
+    durability: QoSDurabilityPolicy::TransientLocal,
+    deadline: QoSDuration::SystemDefault,
+    lifespan: QoSDuration::SystemDefault,
+    liveliness: QoSLivelinessPolicy::SystemDefault,
+    liveliness_lease: QoSDuration::SystemDefault,
+    avoid_ros_namespace_conventions: false,
+};
