Action message support (#417)

* Added action template

* Added action generation

* Added basic create_action_client function

* dded action generation

* checkin

* Fix missing exported pre_field_serde field

* Removed extra code

* Sketch out action server construction and destruction

This follows generally the same pattern as the service server. It
required adding a typesupport function to the Action trait and pulling
in some more rcl_action bindings.

* Fix action typesupport function

* Add ActionImpl trait with internal messages and services

This is incomplete, since the service types aren't yet being generated.

* Split srv.rs.em into idiomatic and rmw template files

This results in the exact same file being produced for services,
except for some whitespace changes. However, it enables actions to
invoke the respective service template for its generation, similar to
how the it works for services and their underlying messages.

* Generate underlying service definitions for actions

Not tested

* Add runtime trait to get the UUID from a goal request

C++ uses duck typing for this, knowing that for any `Action`, the type
`Action::Impl::SendGoalService::Request` will always have a `goal_id`
field of type `unique_identifier_msgs::msg::UUID` without having to
prove this to the compiler. Rust's generics are more strict, requiring
that this be proven using type bounds.

The `Request` type is also action-specific as it contains a `goal` field
containing the `Goal` message type of the action. We therefore cannot
enforce that all `Request`s are a specific type in `rclrs`.

This seems most easily represented using associated type bounds on the
`SendGoalService` associated type within `ActionImpl`. To avoid
introducing to `rosidl_runtime_rs` a circular dependency on message
packages like `unique_identifier_msgs`, the `ExtractUuid` trait only
operates on a byte array rather than a more nicely typed `UUID` message
type.

I'll likely revisit this as we introduce more similar bounds on the
generated types.

* Integrate RMW message methods into ActionImpl

Rather than having a bunch of standalone traits implementing various
message functions like `ExtractUuid` and `SetAccepted`, with the
trait bounds on each associated type in `ActionImpl`, we'll instead add
these functions directly to the `ActionImpl` trait. This is simpler on
both the rosidl_runtime_rs and the rclrs side.

* Add rosidl_runtime_rs::ActionImpl::create_feedback_message()

Adds a trait method to create a feedback message given the goal ID and
the user-facing feedback message type. Depending on how many times we do
this, it may end up valuable to define a GoalUuid type in
rosidl_runtime_rs itself. We wouldn't be able to utilize the
`RCL_ACTION_UUID_SIZE` constant imported from `rcl_action`, but this is
pretty much guaranteed to be 16 forever.

Defining this method signature also required inverting the super-trait
relationship between Action and ActionImpl. Now ActionImpl is the
sub-trait as this gives it access to all of Action's associated types.
Action doesn't need to care about anything from ActionImpl (hopefully).

* Add GetResultService methods to ActionImpl

* Implement ActionImpl trait methods in generator

These still don't build without errors, but it's close.

* Replace set_result_response_status with create_result_response

rclrs needs to be able to generically construct result responses,
including the user-defined result field.

* Implement client-side trait methods for action messages

This adds methods to ActionImpl for creating and accessing
action-specific message types. These are needed by the rclrs
ActionClient to generically read and write RMW messages.

Due to issues with qualified paths in certain places
(rust-lang/rust#86935), the generator now
refers directly to its service and message types rather than going
through associated types of the various traits. This also makes the
generated code a little easier to read, with the trait method signatures
from rosidl_runtime_rs still enforcing type-safety.

* Format the rosidl_runtime_rs::ActionImpl trait

* Wrap longs lines in rosidl_generator_rs action.rs

This at least makes the template easier to read, but also helps with the
generated code. In general, the generated code could actually fit on one
line for the function signatures, but it's not a big deal to split it
across multiple.

* Use idiomatic message types in Action trait

This is user-facing and so should use the friendly message types.

* Cleanup ActionImpl using type aliases

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

* Formatting

* Switch from std::os::raw::c_void to std::ffi::c_void

While these are aliases of each other, we might as well use the more
appropriate std::ffi version, as requested by reviewers.

* Clean up rosidl_generator_rs's cmake files

Some of the variables are present but no longer used. Others were not
updated with the action changes.

* Add a short doc page on the message generation pipeline

This should help newcomers orient themselves around the rosidl_*_rs
packages.

---------

Signed-off-by: Michael X. Grey <[email protected]>
Co-authored-by: Esteve Fernandez <[email protected]>
Co-authored-by: Michael X. Grey <[email protected]>

Author: 3 people

docs/message-generation.md

@@ -0,0 +1,49 @@
+# `ros2_rust` Message Generation
+
+The `ros2_rust` project strives to maintain consistency with the upstream ROS 2 message generation
+system. To this end, it provides two main packages: `rosidl_generator_rs` and `rosidl_runtime_rs`.
+These packages provide the infrastructure required for defining and using ROS 2 messages, services,
+and actions in Rust.
+
+At a high level, the `rosidl_generator_rs` package handles generation of interface crates from the
+`.msg`, `.srv`, and `.action` files defined by a user. The `rosidl_runtime_rs` package provides
+common functionality shared across message packages, such as support types and traits. Each of these
+packages is described in more detail below.
+
+## `rosidl_generator_rs`
+
+`rosidl_generator_rs` follows a very similar pattern to the other message generation packages for
+ROS 2. To tie into this pipeline, it registers itself as a `"rosidl_generate_idl_interfaces"`
+extension with `ament`. Doing so ensures that message packages calling `rosidl_generate_interfaces`
+will invoke the Rust language generator in addition to any others. This is accomplished using the
+various CMake scripts under the `cmake` directory. When this happens, the input interface files will
+be converted into IDL files which, along with additional metadata, are fed into the `generate_rs`
+function of `rosidl_generator_rs/__init__.py`.
+
+From here, the IDL files are parsed into an internal representation using the upstream
+[`rosidl_parser`](https://github.com/ros2/rosidl/tree/rolling/rosidl_parser) package. This abstract
+representation is then used to instantiate the various template files under the `resource`
+subdirectory, producing a full Rust crate for each package.
+
+For each input message type, two `struct`s are generated:
+
+- An ergonomic representation of the message, using more idiomatic `std` types like `Vec` and
+  `String` for sequence and string fields. These are placed directly in the `msg` submodule of the
+  crate.
+- A FFI-suitable `struct` that is ABI-compatible with the layout expected by the RMW layer. While
+  less ergonomic, these avoid the conversion overhead when passed to RMW. These `struct`s are placed
+  under the `msg::rmw` submodule.
+
+All the produced `struct`s implement the standard traits from `std` when possible, such as `Clone`,
+`PartialEq`, and `Debug`. Additionally, when the generated crate's `serde` feature is enabled, these
+structs implement the `Serialize` and `Deserialize` traits.
+
+## `rosidl_runtime_rs`
+
+`rosidl_runtime_rs` is a runtime support package, providing `Message`, `Service`, and `Action`
+traits that are implemented by the corresponding structs generated by `rosidl_generator_rs`. These
+allow for generic interaction with these various interface types, both in client libraries like
+`rclrs` and in user code.
+
+The package also provides a number of string and sequence types that are ABI-compatible with their
+`rosidl_runtime_c` equivalents. This allows for more ergonomic use of the RMW-native message types.

rosidl_generator_rs/cmake/custom_command.cmake

@@ -14,12 +14,10 @@
 
 add_custom_command(
   OUTPUT
-  ${_generated_extension_files}
   ${_generated_common_rs_files}
   ${_generated_msg_rs_files}
-  ${_generated_msg_c_files}
   ${_generated_srv_rs_files}
-  ${_generated_srv_c_files}
+  ${_generated_action_rs_files}
   COMMAND ${PYTHON_EXECUTABLE} ${rosidl_generator_rs_BIN}
   --generator-arguments-file "${generator_arguments_file}"
   --typesupport-impls "${_typesupport_impls}"
@@ -34,11 +32,9 @@ else()
   add_custom_target(
     ${rosidl_generate_interfaces_TARGET}${_target_suffix} ALL
     DEPENDS
-    ${_generated_extension_files}
     ${_generated_common_rs_files}
     ${_generated_msg_rs_files}
-    ${_generated_msg_c_files}
     ${_generated_srv_rs_files}
-    ${_generated_srv_c_files}
+    ${_generated_action_rs_files}
   )
 endif()

rosidl_generator_rs/cmake/rosidl_generator_rs_generate_interfaces.cmake

@@ -26,9 +26,11 @@ set(_generated_common_rs_files "")
 
 set(_generated_msg_rs_files "")
 set(_generated_srv_rs_files "")
+set(_generated_action_rs_files "")
 
 set(_has_msg FALSE)
 set(_has_srv FALSE)
+set(_has_action FALSE)
 
 foreach(_idl_file ${rosidl_generate_interfaces_ABS_IDL_FILES})
   get_filename_component(_parent_folder "${_idl_file}" DIRECTORY)
@@ -37,13 +39,13 @@ foreach(_idl_file ${rosidl_generate_interfaces_ABS_IDL_FILES})
 
   if(_parent_folder STREQUAL "msg")
     set(_has_msg TRUE)
-    set(_idl_file_without_actions ${_idl_file_without_actions} ${_idl_file})
+    set(_idl_files ${_idl_files} ${_idl_file})
   elseif(_parent_folder STREQUAL "srv")
     set(_has_srv TRUE)
-    set(_idl_file_without_actions ${_idl_file_without_actions} ${_idl_file})
+    set(_idl_files ${_idl_files} ${_idl_file})
   elseif(_parent_folder STREQUAL "action")
     set(_has_action TRUE)
-    message(WARNING "Rust actions generation is not implemented")
+    set(_idl_files ${_idl_files} ${_idl_file})
   else()
     message(FATAL_ERROR "Interface file with unknown parent folder: ${_idl_file}")
   endif()
@@ -67,6 +69,12 @@ if(${_has_srv})
   )
 endif()
 
+if(${_has_action})
+  list(APPEND _generated_action_rs_files
+    "${_output_path}/rust/src/action.rs"
+  )
+endif()
+
 set(_dependency_files "")
 set(_dependencies "")
 foreach(_pkg_name ${rosidl_generate_interfaces_DEPENDENCY_PACKAGE_NAMES})
@@ -81,12 +89,15 @@ endforeach()
 set(target_dependencies
   "${rosidl_generator_rs_BIN}"
   ${rosidl_generator_rs_GENERATOR_FILES}
+  "${rosidl_generator_rs_TEMPLATE_DIR}/action.rs.em"
   "${rosidl_generator_rs_TEMPLATE_DIR}/msg_idiomatic.rs.em"
   "${rosidl_generator_rs_TEMPLATE_DIR}/msg_rmw.rs.em"
   "${rosidl_generator_rs_TEMPLATE_DIR}/msg.rs.em"
+  "${rosidl_generator_rs_TEMPLATE_DIR}/srv_idiomatic.rs.em"
+  "${rosidl_generator_rs_TEMPLATE_DIR}/srv_rmw.rs.em"
   "${rosidl_generator_rs_TEMPLATE_DIR}/srv.rs.em"
   ${rosidl_generate_interfaces_ABS_IDL_FILES}
-  ${_idl_file_without_actions}
+  ${_idl_files}
   ${_dependency_files})
 foreach(dep ${target_dependencies})
   if(NOT EXISTS "${dep}")
@@ -99,7 +110,7 @@ rosidl_write_generator_arguments(
   "${generator_arguments_file}"
   PACKAGE_NAME "${PROJECT_NAME}"
   IDL_TUPLES "${rosidl_generate_interfaces_IDL_TUPLES}"
-  ROS_INTERFACE_FILES "${_idl_file_without_actions}"
+  ROS_INTERFACE_FILES "${_idl_files}"
   ROS_INTERFACE_DEPENDENCIES "${_dependencies}"
   OUTPUT_DIR "${_output_path}"
   TEMPLATE_DIR "${rosidl_generator_rs_TEMPLATE_DIR}"
@@ -130,6 +141,7 @@ set_property(
   ${_generated_common_rs_files}
   ${_generated_msg_rs_files}
   ${_generated_srv_rs_files}
+  ${_generated_action_rs_files}
   PROPERTY GENERATED 1)
 
 set(_rsext_suffix "__rsext")
@@ -144,7 +156,8 @@ endif()
 if(BUILD_TESTING AND rosidl_generate_interfaces_ADD_LINTER_TESTS)
   if(
     NOT _generated_msg_rs_files STREQUAL "" OR
-    NOT _generated_srv_rs_files STREQUAL ""
+    NOT _generated_srv_rs_files STREQUAL "" OR
+    NOT _generated_action_rs_files STREQUAL ""
   )
   # TODO(esteve): add linters for Rust files
   endif()

rosidl_generator_rs/resource/action.rs.em

@@ -0,0 +1,205 @@
+@{
+from rosidl_parser.definition import (
+    ACTION_FEEDBACK_MESSAGE_SUFFIX,
+    ACTION_FEEDBACK_SUFFIX,
+    ACTION_GOAL_SERVICE_SUFFIX,
+    ACTION_GOAL_SUFFIX,
+    ACTION_RESULT_SERVICE_SUFFIX,
+    ACTION_RESULT_SUFFIX,
+    SERVICE_REQUEST_MESSAGE_SUFFIX,
+    SERVICE_RESPONSE_MESSAGE_SUFFIX,
+)
+
+action_msg_specs = []
+
+for subfolder, action in action_specs:
+    action_msg_specs.append((subfolder, action.goal))
+    action_msg_specs.append((subfolder, action.result))
+    action_msg_specs.append((subfolder, action.feedback))
+    action_msg_specs.append((subfolder, action.feedback_message))
+
+action_srv_specs = []
+
+for subfolder, action in action_specs:
+    action_srv_specs.append((subfolder, action.send_goal_service))
+    action_srv_specs.append((subfolder, action.get_result_service))
+}@
+
+pub mod rmw {
+@{
+TEMPLATE(
+    'msg_rmw.rs.em',
+    package_name=package_name, interface_path=interface_path,
+    msg_specs=action_msg_specs,
+    get_rs_name=get_rs_name, get_rmw_rs_type=get_rmw_rs_type,
+    pre_field_serde=pre_field_serde,
+    get_idiomatic_rs_type=get_idiomatic_rs_type,
+    constant_value_to_rs=constant_value_to_rs)
+
+TEMPLATE(
+    'srv_rmw.rs.em',
+    package_name=package_name, interface_path=interface_path,
+    srv_specs=action_srv_specs,
+    get_rs_name=get_rs_name, get_rmw_rs_type=get_rmw_rs_type,
+    pre_field_serde=pre_field_serde,
+    get_idiomatic_rs_type=get_idiomatic_rs_type,
+    constant_value_to_rs=constant_value_to_rs)
+}@
+}  // mod rmw
+
+@{
+TEMPLATE(
+    'msg_idiomatic.rs.em',
+    package_name=package_name, interface_path=interface_path,
+    msg_specs=action_msg_specs,
+    get_rs_name=get_rs_name, get_rmw_rs_type=get_rmw_rs_type,
+    pre_field_serde=pre_field_serde,
+    get_idiomatic_rs_type=get_idiomatic_rs_type,
+    constant_value_to_rs=constant_value_to_rs)
+}@
+
+@{
+TEMPLATE(
+    'srv_idiomatic.rs.em',
+    package_name=package_name, interface_path=interface_path,
+    srv_specs=action_srv_specs,
+    get_rs_name=get_rs_name, get_rmw_rs_type=get_rmw_rs_type,
+    pre_field_serde=pre_field_serde,
+    get_idiomatic_rs_type=get_idiomatic_rs_type,
+    constant_value_to_rs=constant_value_to_rs)
+}@
+
+@[for subfolder, action_spec in action_specs]
+
+@{
+type_name = action_spec.namespaced_type.name
+}@
+
+#[link(name = "@(package_name)__rosidl_typesupport_c")]
+extern "C" {
+    fn rosidl_typesupport_c__get_action_type_support_handle__@(package_name)__@(subfolder)__@(type_name)() -> *const std::ffi::c_void;
+}
+
+// Corresponds to @(package_name)__@(subfolder)__@(type_name)
+pub struct @(type_name);
+
+impl rosidl_runtime_rs::Action for @(type_name) {
+  type Goal = crate::@(subfolder)::@(type_name)@(ACTION_GOAL_SUFFIX);
+  type Result = crate::@(subfolder)::@(type_name)@(ACTION_RESULT_SUFFIX);
+  type Feedback = crate::@(subfolder)::@(type_name)@(ACTION_FEEDBACK_SUFFIX);
+
+  fn get_type_support() -> *const std::ffi::c_void {
+    // SAFETY: No preconditions for this function.
+    unsafe { rosidl_typesupport_c__get_action_type_support_handle__@(package_name)__@(subfolder)__@(type_name)() }
+  }
+}
+
+impl rosidl_runtime_rs::ActionImpl for @(type_name) {
+  type GoalStatusMessage = action_msgs::msg::rmw::GoalStatusArray;
+  type FeedbackMessage = crate::@(subfolder)::rmw::@(type_name)@(ACTION_FEEDBACK_MESSAGE_SUFFIX);
+
+  type SendGoalService = crate::@(subfolder)::rmw::@(type_name)@(ACTION_GOAL_SERVICE_SUFFIX);
+  type CancelGoalService = action_msgs::srv::rmw::CancelGoal;
+  type GetResultService = crate::@(subfolder)::rmw::@(type_name)@(ACTION_RESULT_SERVICE_SUFFIX);
+
+  fn create_goal_request(
+    goal_id: &[u8; 16],
+    goal: crate::@(subfolder)::rmw::@(type_name)@(ACTION_GOAL_SUFFIX),
+  ) -> crate::@(subfolder)::rmw::@(type_name)@(ACTION_GOAL_SERVICE_SUFFIX)@(SERVICE_REQUEST_MESSAGE_SUFFIX) {
+    crate::@(subfolder)::rmw::@(type_name)@(ACTION_GOAL_SERVICE_SUFFIX)@(SERVICE_REQUEST_MESSAGE_SUFFIX) {
+      goal_id: unique_identifier_msgs::msg::rmw::UUID { uuid: *goal_id },
+      goal,
+    }
+  }
+
+  fn get_goal_request_uuid(
+    request: &crate::@(subfolder)::rmw::@(type_name)@(ACTION_GOAL_SERVICE_SUFFIX)@(SERVICE_REQUEST_MESSAGE_SUFFIX),
+  ) -> &[u8; 16] {
+    &request.goal_id.uuid
+  }
+
+  fn create_goal_response(
+    accepted: bool,
+    stamp: (i32, u32),
+  ) -> crate::@(subfolder)::rmw::@(type_name)@(ACTION_GOAL_SERVICE_SUFFIX)@(SERVICE_RESPONSE_MESSAGE_SUFFIX) {
+    crate::@(subfolder)::rmw::@(type_name)@(ACTION_GOAL_SERVICE_SUFFIX)@(SERVICE_RESPONSE_MESSAGE_SUFFIX) {
+      accepted,
+      stamp: builtin_interfaces::msg::rmw::Time {
+        sec: stamp.0,
+        nanosec: stamp.1,
+      },
+    }
+  }
+
+  fn get_goal_response_accepted(
+    response: &crate::@(subfolder)::rmw::@(type_name)@(ACTION_GOAL_SERVICE_SUFFIX)@(SERVICE_RESPONSE_MESSAGE_SUFFIX),
+  ) -> bool {
+    response.accepted
+  }
+
+  fn get_goal_response_stamp(
+    response: &crate::@(subfolder)::rmw::@(type_name)@(ACTION_GOAL_SERVICE_SUFFIX)@(SERVICE_RESPONSE_MESSAGE_SUFFIX),
+  ) -> (i32, u32) {
+    (response.stamp.sec, response.stamp.nanosec)
+  }
+
+  fn create_feedback_message(
+    goal_id: &[u8; 16],
+    feedback: crate::@(subfolder)::rmw::@(type_name)@(ACTION_FEEDBACK_SUFFIX),
+  ) -> crate::@(subfolder)::rmw::@(type_name)@(ACTION_FEEDBACK_MESSAGE_SUFFIX) {
+    let mut message = crate::@(subfolder)::rmw::@(type_name)@(ACTION_FEEDBACK_MESSAGE_SUFFIX)::default();
+    message.goal_id.uuid = *goal_id;
+    message.feedback = feedback;
+    message
+  }
+
+  fn get_feedback_message_uuid(
+    feedback: &crate::@(subfolder)::rmw::@(type_name)@(ACTION_FEEDBACK_MESSAGE_SUFFIX),
+  ) -> &[u8; 16] {
+    &feedback.goal_id.uuid
+  }
+
+  fn get_feedback_message_feedback(
+    feedback: &crate::@(subfolder)::rmw::@(type_name)@(ACTION_FEEDBACK_MESSAGE_SUFFIX),
+  ) -> &crate::@(subfolder)::rmw::@(type_name)@(ACTION_FEEDBACK_SUFFIX) {
+    &feedback.feedback
+  }
+
+  fn create_result_request(
+    goal_id: &[u8; 16],
+  ) -> crate::@(subfolder)::rmw::@(type_name)@(ACTION_RESULT_SERVICE_SUFFIX)@(SERVICE_REQUEST_MESSAGE_SUFFIX) {
+    crate::@(subfolder)::rmw::@(type_name)@(ACTION_RESULT_SERVICE_SUFFIX)@(SERVICE_REQUEST_MESSAGE_SUFFIX) {
+      goal_id: unique_identifier_msgs::msg::rmw::UUID { uuid: *goal_id },
+    }
+  }
+
+  fn get_result_request_uuid(
+    request: &crate::@(subfolder)::rmw::@(type_name)@(ACTION_RESULT_SERVICE_SUFFIX)@(SERVICE_REQUEST_MESSAGE_SUFFIX),
+  ) -> &[u8; 16] {
+    &request.goal_id.uuid
+  }
+
+  fn create_result_response(
+    status: i8,
+    result: crate::@(subfolder)::rmw::@(type_name)@(ACTION_RESULT_SUFFIX),
+  ) -> crate::@(subfolder)::rmw::@(type_name)@(ACTION_RESULT_SERVICE_SUFFIX)@(SERVICE_RESPONSE_MESSAGE_SUFFIX) {
+    crate::@(subfolder)::rmw::@(type_name)@(ACTION_RESULT_SERVICE_SUFFIX)@(SERVICE_RESPONSE_MESSAGE_SUFFIX) {
+      status,
+      result,
+    }
+  }
+
+  fn get_result_response_result(
+    response: &crate::@(subfolder)::rmw::@(type_name)@(ACTION_RESULT_SERVICE_SUFFIX)@(SERVICE_RESPONSE_MESSAGE_SUFFIX),
+  ) -> &crate::@(subfolder)::rmw::@(type_name)@(ACTION_RESULT_SUFFIX) {
+    &response.result
+  }
+
+  fn get_result_response_status(
+    response: &crate::@(subfolder)::rmw::@(type_name)@(ACTION_RESULT_SERVICE_SUFFIX)@(SERVICE_RESPONSE_MESSAGE_SUFFIX),
+  ) -> i8 {
+    response.status
+  }
+}
+
+@[end for]

rosidl_generator_rs/resource/lib.rs.em

@@ -7,3 +7,7 @@ pub mod msg;
 @[if len(srv_specs) > 0]@
 pub mod srv;
 @[end if]@
+
+@[if len(action_specs) > 0]@
+pub mod action;
+@[end if]@

rosidl_generator_rs/resource/msg_rmw.rs.em

@@ -19,7 +19,7 @@ type_name = msg_spec.structure.namespaced_type.name
 
 #[link(name = "@(package_name)__rosidl_typesupport_c")]
 extern "C" {
-    fn rosidl_typesupport_c__get_message_type_support_handle__@(package_name)__@(subfolder)__@(type_name)() -> *const std::os::raw::c_void;
+    fn rosidl_typesupport_c__get_message_type_support_handle__@(package_name)__@(subfolder)__@(type_name)() -> *const std::ffi::c_void;
 }
 
 #[link(name = "@(package_name)__rosidl_generator_c")]
@@ -103,7 +103,7 @@ impl rosidl_runtime_rs::Message for @(type_name) {
 
 impl rosidl_runtime_rs::RmwMessage for @(type_name) where Self: Sized {
   const TYPE_NAME: &'static str = "@(package_name)/@(subfolder)/@(type_name)";
-  fn get_type_support() -> *const std::os::raw::c_void {
+  fn get_type_support() -> *const std::ffi::c_void {
     // SAFETY: No preconditions for this function.
     unsafe { rosidl_typesupport_c__get_message_type_support_handle__@(package_name)__@(subfolder)__@(type_name)() }
   }