feat: add coding guideline about topic message handling

docs/contributing/coding-guidelines/ros-nodes/topic-message-handling/00-topic-message-handling.md

@@ -0,0 +1,187 @@
+# Topic message handling guideline
+
+## Introduction
+
+Here is coding guideline for a topic message handling method which includes more enhanced method than usually used one, which is roughly explained in [Discussions page](https://github.com/orgs/autowarefoundation/discussions/4612). Refer to the page to understand the basic concept of the enhanced method.
+You can find sample source codes in [ros2_subscription_examples](https://github.com/takam5f2/ros2_subscription_examples) referred from this document.
+
+## Typical message handling method usually used
+
+At first, let us see a typical message handling method usually used.
+In a typical ROS 2 application, a topic message which is received by Subscription is referred to and processed by a dedicated callback function.
+
+```c++
+  steer_sub_ = create_subscription<SteeringReport>(
+    "input/steering", 1,
+    [this](SteeringReport::SharedPtr msg) { current_steer_ = msg->steering_tire_angle; });
+```
+
+In code above, when a topic message whose name is `input/steering` is received, an anonymous function whose description is `{current_steer_ = msg->steering_tier_angle;}` is executed as a callback in a thread. The callback function is always executed when the message is received, which leads to waste computing resource if the message is not always necessary. Besides, it costs thread-wakeup overhread just to take a message.
+
+## Enhanced method
+
+There is an enhanced method to take a message using `Subscription->take()` method only when it is needed.
+Here is a sample code to use `Subscription->take()` method executed as a timer or subscription callback to perform a main logic.
+In this case, a topic message is not obtained by a subscription callback. To be exact, you need to program your code so that a callback function is not called automatically.
+
+```c++
+  SteeringReport::SharedPtr msg;
+  rclcpp::MessageInfo msg_info;
+  if (sub_->take(msg, msg_info)) {
+    // processing and publishing after this
+```
+
+By using this manner, following advantages are achieved.
+
+- it can reduce invocations of subscription callback functions which is relatively expensive
+- there is no need to take a topic message which is not read
+- there is no need of exclusive lock between a subscription callback thread and a timer callback thread
+
+## Methods to handle topic message data
+
+We will explain four methods including the enhanced method.
+
+### 1. obtain data by calling `Subscription->take()`
+
+To use the enhanced method using `Subscription->take()`, you need to do two things below basically.
+
+1. prevent calling a callback function when a topic message is received
+2. call `take()` method of Subscription object when a topic message is needed
+
+You can see an example of the typical usage of `take()` method in [ros2_subscription_examples/simple_examples/src
+/timer_listener.cpp](https://github.com/takam5f2/ros2_subscription_examples/blob/main/simple_examples/src/timer_listener.cpp).
+
+#### prevent calling a callback function
+
+It is needed to create a Subscription object with a callback group which makes registered callback functions not called automtically.
+Note that it is needed to register a callback function to Subscription object even if the function will not be called. If you register `nullptr` instead of a callback function, it can not be built.
+Here is a sample code excerpted from [ros2_subscription_examples/simple_examples/src/timer_listener.cpp](https://github.com/takam5f2/ros2_subscription_examples/blob/main/simple_examples/src/timer_listener.cpp).
+
+```c++
+    rclcpp::CallbackGroup::SharedPtr cb_group_noexec = this->create_callback_group(
+        rclcpp::CallbackGroupType::MutuallyExclusive, false);
+    auto subscription_options = rclcpp::SubscriptionOptions();
+    subscription_options.callback_group = cb_group_noexec;
+
+    rclcpp::QoS qos(rclcpp::KeepLast(10));
+    if (use_transient_local) {
+      qos = qos.transient_local();
+    }
+
+    sub_ = create_subscription<std_msgs::msg::String>("chatter", qos, not_executed_callback, subscription_options);
+```
+
+In code above, `cb_group_noexec` is created by calling `create_callback_group` with its second argument `false`. A callback function which belongs to the callback group will not be called by Executor.
+If `callback_group` member of `subscription_options` is set to `cb_group_noexec`, `not_executed_callback` will not be called when a corresponded topic message `chatter` is received.
+The second argument of `create_callback_group` is defined as below.
+
+```c++
+rclcpp::CallbackGroup::SharedPtr create_callback_group(rclcpp::CallbackGroupType group_type, \
+                                  bool automatically_add_to_executor_with_node = true)
+```
+
+If `automatically_add_to_executor_with_node` is set to `true`, callback functions included in a node which is added to Executor will be called automatically by Executor.
+
+#### call `take()` method of Subscription object
+
+Here is a sample code excerpted from [ros2_subscription_examples/simple_examples/src/timer_listener.cpp](https://github.com/takam5f2/ros2_subscription_examples/blob/main/simple_examples/src/timer_listener.cpp) in which `take()` method is used.
+
+```c++
+  std_msgs::msg::String msg;
+  rclcpp::MessageInfo msg_info;
+  if (sub_->take(msg, msg_info)) {
+    RCLCPP_INFO(this->get_logger(), "Catch message");
+    RCLCPP_INFO(this->get_logger(), "I heard: [%s]", msg.data.c_str());
+```
+
+In code above, `take(msg, msg_info)` is called in a timer driven callback function by `sub_` instance which is created from Subscription class. `msg` and `msg_info` indicate a message body and meta data of it respectively. When `take(msg, msg_info)` is called, if there is a message in Subscription Queue, then the message is copied to `msg`.
+`take(msg, msg_info)` returns `true` if a message is received from Subscription successfully. In this case in code above, a content of the message is outputted by `RCLCPP_INFO`.
+`take(msg, msg_info)` returns `false` if a mesage is not received from Subscription.
+When `take(msg, msg_info)` is called, if the size of Subscription Queue is larger than one and there are two or more messages in the queue, then the oldest message is copied to `msg`. If the size of Queue is one, the latest message is always obtained.
+
+Note 1. `take()` method is irreversible in terms that a obtained message by `take()` method can not be returned to Subscription Queue. **You can determine whether a message is in Subscription Queue or not by the return value of `take()` method, but it changes Subscription queue state.** If you want to know whether there is a message in Subscription Queue or not, you can use `rclcpp::WaitSet`.
+Refer to [[supplement] Use rclcpp::WaitSet](./02-supp-waitset.md) for more detail.
+
+Note 2. You can use `take()` method to obtain a message which is passed through DDS as an inter-process communication. You can not use it for an intra-process communication. Refer to [[supplement] Obtain a received message through intra-process communication](./01-supp-intra-process-comm.md) in case of intra-process communication.
+
+#### 1.1 obtain Serialized Message from Subscription
+
+ROS 2 provides Serialized Message functon which supports communication with arbitrary message types as explained in [Class SerializedMessage](http://docs.ros.org/en/humble/p/rclcpp/generated/classrclcpp_1_1SerializedMessage.html). It is used by `topic_state_monitor` in Autoware.
+You need to use `take_serialized()` method instead of `take()` method to obtain a message of Serialized Message type from Subscription object.
+
+Here is a sample code excerpted from [ros2_subscription_examples/simple_examples/src/timer_listener_serialized_message.cpp](https://github.com/takam5f2/ros2_subscription_examples/blob/main/simple_examples/src/timer_listener_serialized_message.cpp).
+
+```c++
+      // receive the serialized message.
+      rclcpp::MessageInfo msg_info;
+      auto msg = sub_->create_serialized_message();
+
+      if (sub_->take_serialized(*msg, msg_info) == false) {
+        return;
+      }
+```
+
+In code above, `msg` is created by `create_serialized_message()` to store a received message, whose type is `std::shared_ptr<rclcpp::SerializedMessage>`. You can obtain a message of Serialized Message type by `take_serialized()` method. Note that `take_serialized()` method needs reference type data as its first argument therefore you need to convert `msg` type using `*`.
+
+### 2. obtain multiple data stored in Subscription Queue
+
+Subscription can hold multiple messages in its queue. Such messages can be obtained by consecutive calls of `take()` method from a callback function at a time. Note that in a normal manner in which a subscription callback function is used to take a topic message, if there are one or more messages in Subscription Queue, the oldest one is taken and a thread is assigned to execute a callback function, which continues until the queue becomes empty. If you use `take()` method, you can obtain multiple messages at a time.
+
+Here is a sample code excerpted from [ros2_subscription_examples/simple_examples/src/timer_batch_listener.cpp](https://github.com/takam5f2/ros2_subscription_examples/blob/main/simple_examples/src/timer_batch_listener.cpp) in which `take()` method is called consecutively.
+
+```c++
+      std_msgs::msg::String msg;
+      rclcpp::MessageInfo msg_info;
+      while (sub_->take(msg, msg_info))
+      {
+        RCLCPP_INFO(this->get_logger(), "Catch message");
+        RCLCPP_INFO(this->get_logger(), "I heard: [%s]", msg.data.c_str());
+```
+
+In code above, `while(sub->take(msg, msg_info))` continues to take messages from Subscription Queue until the queue becomes empty. While a message is taken, the message is processed each by each.
+Note that you need to determine Subscription Queue size considering frequency of an invocation of a callback function and that of a reception of message. For example, if frequency of an invocation of a callback function is 10Hz and that of a reception of message is 50Hz, Subscription Queue size needs to be at least 5 for messages not to be lost.
+
+To assign a thread and let it execute a callback function each time a message is received leads to increase overhead in terms of performance. You can use the method introduced in this section to avoid the overhead.
+It is effective to use the method if a reception of message occurs very frequently but it doesn't need to be processed with so high frequency. For example, if a message is received with more than 100 Hz such as CAN message, it is desirable to obtain multiple messages in a callback function at a time with one thread invocation.
+
+### 3. obtain data by calling `Subscription->take` and then call a callback function
+
+If you want to use the enhanced method introduced in this guideline, you may feel it is needed to implement a new funcation in which a message is taken by `take()` method and then processed. But there is a way to make a callback function be called indirectly which is registered to Subscription object.
+Here is a sample code excerpted from [ros2_subscription_examples/simple_examples/src/timer_listener_using_callback.cpp](https://github.com/takam5f2/ros2_subscription_examples/blob/main/simple_examples/src/timer_listener_using_callback.cpp).
+
+```c++
+      auto msg = sub_->create_message();
+      rclcpp::MessageInfo msg_info;
+      if (sub_->take_type_erased(msg.get(), msg_info)) {
+        sub_->handle_message(msg, msg_info);
+
+```
+
+In code above, a message is taken by `take_type_erased()` method before calling a registered callback function. Note that you need to use `take_type_erased()` instead of `take()` and that `take_type_erased()` needs `void` type data as its first argument. You need to use `get()` method to convert `msg` whose type is `shared_ptr<void>` to `void` type. Then `handle_message()` method is called with the obtained message. A registered callback function is called inside of `handle_message()`.
+You don't need to take special care of message type which is passed to `take_type_erased()`, the same as `take_type_erased()` and `handle_message()` are not based on any specific types. You can define message variable as `auto msg = sub_->create_message();`.
+You can also refer to [API document](http://docs.ros.org/en/humble/p/rclcpp/generated/classrclcpp_1_1SubscriptionBase.html#_CPPv4N6rclcpp16SubscriptionBase16take_type_erasedEPvRN6rclcpp11MessageInfoE) as for `create_message()`, `take_type_erased()` and `handle_message()`.
+
+### 4. obtain data by a callback function
+
+A typical method usually used is also usable, by which a message is obtained in subscription callback function . If you don't use a callback group with `automatically_add_to_executor_with_node = false`, a registered callback function is called automatically by Executor when a topic message is received.
+One of advantages of this method is you don't need to take care whether a topic message is passed through inter-process or itra-process. Remind that in the enhanced method, `take()` can only be used in case of inter-process communication while `take_type_erased()` needs to be used in case of intra-process communication.
+
+## Appendix
+
+A callback function is used to obtain a topic message in many of ROS 2 applications as if it is a rule or a custom. As we have seen, you can use `Subscription->take()` method to obtain a topic message without calling a subscription callback function.
+This method is also documented in [Template Class Subscription — rclcpp 16.0.8 documentation](https://docs.ros.org/en/humble/p/rclcpp/generated/classrclcpp_1_1Subscription.html#_CPPv4N6rclcpp12Subscription4takeER14ROSMessageTypeRN6rclcpp11MessageInfoE).
+Many of ROS 2 users may feel anxious to use `take()` method because they may not be so familiar with it, but it is widely used in Executor implementation as in [rclcpp/executor.cpp](https://github.com/ros2/rclcpp/blob/47c977d1bc82fc76dd21f870bcd3ea473eca2f59/rclcpp/src/rclcpp/executor.cpp#L643-L648) shown below. Therefore it turns out that you use `take()` method indirectly whether you know it or not.
+
+```c++
+    std::shared_ptr<void> message = subscription->create_message();
+    take_and_do_error_handling(
+      "taking a message from topic",
+      subscription->get_topic_name(),
+      [&]() {return subscription->take_type_erased(message.get(), message_info);},
+      [&]() {subscription->handle_message(message, message_info);});
+```
+
+Note: Strictly speaking, `take_type_erased()` method is called in Executor implementation instead of `take()`.
+But `take_type_erased()` is called inside of `take()`.
+
+If Executor is programmed to call a callback function, Executor itself determines when to do it. Because Executor calls a callback function with best-effort basis basically, it can occur that a message is not referred to or processed when it is needed in a node. Therefore it is desirable to call `take()` method directly **to ensue that a message is referred to or processed at the intended time.**

docs/contributing/coding-guidelines/ros-nodes/topic-message-handling/01-supp-intra-process-comm.md

@@ -0,0 +1,71 @@
+# [supplement] Obtain a received message through intra-process communication
+
+## Topic message handling in intra-process communication
+
+rlcpp supports intra-process communication. As explained in [Topic message handling guideline](00-topic-message-handling.md), `take()` method of Subscription can not be used in case of intra-process communication. `take()` can not obtain a topic message which is received through inter-process communication. Besides, even though a method is provided to obtain a received topic message through intra-process communication, a method is not provided to refer to the message directly.
+But a method are provided for intra-process communication similar to a method for inter-process communication described in [obtain data by calling Subscription->take and then call a callback function](../00-topic-message-handling/#3-obtain-data-by-calling-subscription-take-and-then-call-a-callback-function).
+`take_data()` method is provided to obtain a received data in case of intra-process communication and the received data must be processed through `execute()` method.
+Refer to [Template Class SubscriptionIntraProcess — rclcpp 16.0.8 documentation](http://docs.ros.org/en/humble/p/rclcpp/generated/classrclcpp_1_1experimental_1_1SubscriptionIntraProcess.html#_CPPv4N6rclcpp12experimental24SubscriptionIntraProcess9take_dataEv) for `take_data()` and `execute()` for more detail.
+
+## coding method
+
+Call `take_data()` method and then `execute()` method as below.
+
+```c++
+// Execute any entities of the Waitable that may be ready
+std::shared_ptr<void> data = waitable.take_data();
+waitable.execute(data);
+```
+
+Here is a sample program in [ros2_subscription_examples/intra_process_talker_listener/src/timer_listener_intra_process.cpp at main · takam5f2/ros2_subscription_examples](https://github.com/takam5f2/ros2_subscription_examples/blob/main/intra_process_talker_listener/src/timer_listener_intra_process.cpp).
+You can run the program as below. If you set `true` to `use_intra_process_comms`, intra-process communication is performed, while if you set `false`, inter-process communication is performed.
+
+```console
+ros2 intra_process_talker_listener talker_listener_intra_process.launch.py use_intra_process_comms:=true
+```
+
+Here is a excerption from [ros2_subscription_examples/intra_process_talker_listener/src/timer_listener_intra_process.cpp at main · takam5f2/ros2_subscription_examples](https://github.com/takam5f2/ros2_subscription_examples/blob/main/intra_process_talker_listener/src/timer_listener_intra_process.cpp).
+
+```c++
+      // check if intra-process communication is enabled.
+      if (this->get_node_options().use_intra_process_comms()){
+
+        // get the intra-process subscription's waitable.
+        auto intra_process_sub = sub_->get_intra_process_waitable();
+
+        // check if the waitable has data.
+        if (intra_process_sub->is_ready(nullptr) == true) {
+
+          // take the data and execute the callback.
+          std::shared_ptr<void> data = intra_process_sub->take_data();
+
+          RCLCPP_INFO(this->get_logger(), " Intra-process communication is performed.");
+
+          // execute the callback.
+          intra_process_sub->execute(data);
+```
+
+Below is explanation of above code one line by one.
+
+- `if (this->get_node_options().use_intra_process_comms()){`
+
+  - verify intra-process communication is enabled or not by using NodeOptions
+
+- `auto intra_process_sub = sub_->get_intra_process_waitable();`
+
+  - get an object which is used by Subscription in case of intra-process communication
+
+- `if (intra_process_sub->is_ready(nullptr) == true) {`
+
+  - check if a message has already been received through intra-process communication
+  - the argument of `is_ready()` is of rcl_wait_set_t type, but because the argument is not used inside `is_ready()`, `nullptr` is used tentatively
+    - using `nullptr` is a workaround at this point of time, because it is not preferable
+
+- `std::shared_ptr<void> data = intra_process_sub->take_data();`
+
+  - obtain a topic message
+  - `intra_process_sub->take_data()` does not return Boolean value which indicates a message is received successfully or not, therefore it is needed to verify it by calling `is_ready()` in advance
+
+- `intra_process_sub->execute(data);`
+  - a callback function corresponded to the received message is called inside `execute()`
+  - the callback function is executed by the thread which executes `execute()` without context switch