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

rosidl_runtime_rs/src/lib.rs

@@ -9,4 +9,4 @@ mod string;
 pub use string::{BoundedString, BoundedWString, String, StringExceedsBoundsError, WString};
 
 mod traits;
-pub use traits::{Message, RmwMessage, SequenceAlloc, Service};
+pub use traits::{Action, ActionImpl, Message, RmwMessage, SequenceAlloc, Service};

rosidl_runtime_rs/src/traits.rs

@@ -41,7 +41,7 @@ pub trait RmwMessage: Clone + Debug + Default + Send + Sync + Message {
     const TYPE_NAME: &'static str;
 
     /// Get a pointer to the correct `rosidl_message_type_support_t` structure.
-    fn get_type_support() -> *const std::os::raw::c_void;
+    fn get_type_support() -> *const std::ffi::c_void;
 }
 
 /// Trait for types that can be used in a `rclrs::Subscription` and a `rclrs::Publisher`.
@@ -157,5 +157,97 @@ pub trait Service: 'static {
     type Response: Message;
 
     /// Get a pointer to the correct `rosidl_service_type_support_t` structure.
-    fn get_type_support() -> *const std::os::raw::c_void;
+    fn get_type_support() -> *const std::ffi::c_void;
 }
+
+/// Trait for actions.
+///
+/// User code never needs to call this trait's method, much less implement this trait.
+pub trait Action: 'static {
+    /// The goal message associated with this action.
+    type Goal: Message;
+
+    /// The result message associated with this action.
+    type Result: Message;
+
+    /// The feedback message associated with this action.
+    type Feedback: Message;
+
+    /// Get a pointer to the correct `rosidl_action_type_support_t` structure.
+    fn get_type_support() -> *const std::ffi::c_void;
+}
+
+/// Trait for action implementation details.
+///
+/// User code never needs to implement this trait, nor use its associated types.
+pub trait ActionImpl: 'static + Action {
+    /// The goal_status message associated with this action.
+    type GoalStatusMessage: Message;
+
+    /// The feedback message associated with this action.
+    type FeedbackMessage: Message;
+
+    /// The send_goal service associated with this action.
+    type SendGoalService: Service;
+
+    /// The cancel_goal service associated with this action.
+    type CancelGoalService: Service;
+
+    /// The get_result service associated with this action.
+    type GetResultService: Service;
+
+    /// Create a goal request message with the given UUID and goal.
+    fn create_goal_request(goal_id: &[u8; 16], goal: RmwGoalData<Self>) -> RmwGoalRequest<Self>;
+
+    /// Get the UUID of a goal request.
+    fn get_goal_request_uuid(request: &RmwGoalRequest<Self>) -> &[u8; 16];
+
+    /// Create a goal response message with the given acceptance and timestamp.
+    fn create_goal_response(accepted: bool, stamp: (i32, u32)) -> RmwGoalResponse<Self>;
+
+    /// Get the `accepted` field of a goal response.
+    fn get_goal_response_accepted(response: &RmwGoalResponse<Self>) -> bool;
+
+    /// Get the `stamp` field of a goal response.
+    fn get_goal_response_stamp(response: &RmwGoalResponse<Self>) -> (i32, u32);
+
+    /// Create a feedback message with the given goal ID and contents.
+    fn create_feedback_message(
+        goal_id: &[u8; 16],
+        feedback: RmwFeedbackData<Self>,
+    ) -> RmwFeedbackMessage<Self>;
+
+    /// Get the UUID of a feedback message.
+    fn get_feedback_message_uuid(feedback: &RmwFeedbackMessage<Self>) -> &[u8; 16];
+
+    /// Get the feedback of a feedback message.
+    fn get_feedback_message_feedback(feedback: &RmwFeedbackMessage<Self>)
+        -> &RmwFeedbackData<Self>;
+
+    /// Create a result request message with the given goal ID.
+    fn create_result_request(goal_id: &[u8; 16]) -> RmwResultRequest<Self>;
+
+    /// Get the UUID of a result request.
+    fn get_result_request_uuid(request: &RmwResultRequest<Self>) -> &[u8; 16];
+
+    /// Create a result response message with the given status and contents.
+    fn create_result_response(status: i8, result: RmwResultData<Self>) -> RmwResultResponse<Self>;
+
+    /// Get the result of a result response.
+    fn get_result_response_result(response: &RmwResultResponse<Self>) -> &RmwResultData<Self>;
+
+    /// Get the status of a result response.
+    fn get_result_response_status(response: &RmwResultResponse<Self>) -> i8;
+}
+
+// Type definitions to simplify the ActionImpl trait
+pub type RmwServiceRequest<S> = <<S as Service>::Request as Message>::RmwMsg;
+pub type RmwServiceResponse<S> = <<S as Service>::Response as Message>::RmwMsg;
+pub type RmwGoalRequest<A> = RmwServiceRequest<<A as ActionImpl>::SendGoalService>;
+pub type RmwGoalResponse<A> = RmwServiceResponse<<A as ActionImpl>::SendGoalService>;
+pub type RmwGoalData<A> = <<A as Action>::Goal as Message>::RmwMsg;
+pub type RmwFeedbackData<A> = <<A as Action>::Feedback as Message>::RmwMsg;
+pub type RmwFeedbackMessage<A> = <<A as ActionImpl>::FeedbackMessage as Message>::RmwMsg;
+pub type RmwResultRequest<A> = RmwServiceRequest<<A as ActionImpl>::GetResultService>;
+pub type RmwResultResponse<A> = RmwServiceResponse<<A as ActionImpl>::GetResultService>;
+pub type RmwResultData<A> = <<A as Action>::Result as Message>::RmwMsg;