feat: add coding guideline about topic message handling

docs/contributing/coding-guidelines/ros-nodes/.pages

@@ -8,3 +8,4 @@ nav:
   - parameters.md
   - task-scheduling.md
   - topic-namespaces.md
+  - topic-message-handling

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

@@ -0,0 +1,4 @@
+nav:
+  - index.md
+  - 01-supp-intra-process-comm.md
+  - 02-supp-waitset.md

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](index.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](./index.md#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

docs/contributing/coding-guidelines/ros-nodes/topic-message-handling/02-supp-waitset.md

@@ -0,0 +1,130 @@
+# [supplement] Use rclcpp::WaitSet
+
+## What is `rclcpp::WaitSet`
+
+As explained in [call take() method of Subscription object](./index.md#call-take-method-of-subscription-object), `take()` method is irreversible. Once `take()` method is executed, Subscription object state changes and undo can not be applied, therefore Subscription object can not be restored to previous state. You can use `rclcpp::WaitSet` in advance to call `take()` so that a message is received after verifying it is in Subscription Queue.
+Here is a sample code in which `wait_set_.wait()` tells you that a message has already been received and can be obtained by `take()`.
+
+```c++
+      auto wait_result = wait_set_.wait(std::chrono::milliseconds(0));
+      if (wait_result.kind() == rclcpp::WaitResultKind::Ready &&
+          wait_result.get_wait_set().get_rcl_wait_set().subscriptions[0]) {
+            sub_->take(msg, msg_info);
+            RCLCPP_INFO(this->get_logger(), "Catch message");
+            RCLCPP_INFO(this->get_logger(), "I heard: [%s]", msg.data.c_str());
+```
+
+Also you can verify that there are messages in multiple Subscription Queues in advance.
+If your code needs to proceed after several types of messages got together, using `rclcpp::WaitSet` is prefarable.
+
+```c++
+      auto wait_result = wait_set_.wait(std::chrono::milliseconds(0));
+      bool received_all_messages = false;
+      if (wait_result.kind() == rclcpp::WaitResultKind::Ready) {
+        for (auto wait_set_subs : wait_result.get_wait_set().get_rcl_wait_set().subscriptions) {
+          if (!wait_set_subs) {
+            RCLCPP_INFO_THROTTLE(get_logger(), clock, 5000, "Waiting for data...");
+            return {};
+          }
+        }
+        received_all_mesages = true;
+      }
+```
+
+In code above, unless `rclcpp::WaitSet` is used, it is difficult to verify that all needed messages get together.
+
+## Coding method
+
+We will explain coding method of `rclcpp::WaitSet` using a sample code below.
+
+- [ros2_subscription_examples/waitset_examples/src/talker_triple.cpp at main · takam5f2/ros2_subscription_examples](https://github.com/takam5f2/ros2_subscription_examples/blob/main/waitset_examples/src/talker_triple.cpp)
+  - it publishes `/chatter` per one second, `/slower_chatter` per two seconds, and `/slowest_chatter` per three seconds periodically
+- [ros2_subscription_examples/waitset_examples/src/timer_listener_triple_async.cpp at main · takam5f2/ros2_subscription_examples](https://github.com/takam5f2/ros2_subscription_examples/blob/main/waitset_examples/src/timer_listener_triple_async.cpp)
+  - it queries `WaitSet` per one second and if there is a message available, it obtains the message by `take()`
+  - it has each subscription for `/chatter` `/slower_chatter`, and `/slower_chatter`
+
+Following three steps are needed to use `WaitSet`.
+
+### 1. declare and initialize `WaitSet`
+
+You need to declare WaitSet variable first to use.
+Below is excerption from [ros2_subscription_examples/waitset_examples/src/timer_listener_triple_async.cpp at main · takam5f2/ros2_subscription_examples](https://github.com/takam5f2/ros2_subscription_examples/blob/main/waitset_examples/src/timer_listener_triple_async.cpp).
+
+```c++
+rclcpp::WaitSet wait_set_;
+```
+
+Note that there are three types of `WaitSet` as below.
+
+- [Typedef rclcpp::WaitSet](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/typedef_namespacerclcpp_1ad6fb19c154de27e92430309d2da25ac3.html)
+  - Subscription, Timer, and so on can be registered to WaitSet at any time
+- [Typedef rclcpp::ThreadSafeWaitSet](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/typedef_namespacerclcpp_1acaec573e71549fd3078644e18e7f7127.html)
+  - Subscription, Timer, and so on can be registered to WaitSet only in thread-safe state
+  - sample code is here: [examples/rclcpp/wait_set/src/thread_safe_wait_set.cpp at rolling · ros2/examples](https://github.com/ros2/examples/blob/rolling/rclcpp/wait_set/src/thread_safe_wait_set.cpp)
+- [Typedef rclcpp::StaticWaitSet](https://docs.ros.org/en/ros2_packages/humble/api/rclcpp/generated/typedef_namespacerclcpp_1adb06acf4a5723b1445fa6ed4e8f73374.html)
+  - Subscription, Timer, and so on can be registered to WaitSet only at initialization
+  - here are sample codes:
+    - [ros2_subscription_examples/waitset_examples/src/timer_listener_twin_static.cpp at main · takam5f2/ros2_subscription_examples](https://github.com/takam5f2/ros2_subscription_examples/blob/main/waitset_examples/src/timer_listener_twin_static.cpp)
+    - [examples/rclcpp/wait_set/src/static_wait_set.cpp at rolling · ros2/examples](https://github.com/ros2/examples/blob/rolling/rclcpp/wait_set/src/static_wait_set.cpp)
+
+### 2. register trigger (Subscription, Timer, and so on) to `WaitSet`
+
+You need to register a trigger to `WaitSet`.
+Below is excerption from [ros2_subscription_examples/waitset_examples/src/timer_listener_triple_async.cpp at main · takam5f2/ros2_subscription_examples](https://github.com/takam5f2/ros2_subscription_examples/blob/main/waitset_examples/src/timer_listener_triple_async.cpp)
+
+```c++
+    subscriptions_array_[0] = create_subscription<std_msgs::msg::String>("chatter", qos, not_executed_callback, subscription_options);
+    subscriptions_array_[1] = create_subscription<std_msgs::msg::String>("slower_chatter", qos, not_executed_callback, subscription_options);
+    subscriptions_array_[2] = create_subscription<std_msgs::msg::String>("slowest_chatter", qos, not_executed_callback, subscription_options);
+
+    // Add subscription to waitset
+    for (auto & subscription : subscriptions_array_) {
+      wait_set_.add_subscription(subscription);
+    }
+```
+
+In code above, created subscriptions are registered to `WaitSet` by `add_subscription()`.
+You can also register another type of trigger to WaitSet by which a callback function registered to Subscription is invoked, such as Timer, Service, or Action.
+A sample code to register Timer trigger is here.
+
+```c++
+wait_set_.add_timer(much_slower_timer_);
+```
+
+A trigger can be registered at declaration and initialization as [https://github.com/ros2/examples/blob/rolling/rclcpp/wait_set/src/wait_set_topics_and_timer.cpp#L66](https://github.com/ros2/examples/blob/rolling/rclcpp/wait_set/src/wait_set_topics_and_timer.cpp#L66).
+
+### 3. verify WaitSet result
+
+You can see WaitSet result by doing 1 below first and then 2 below.
+
+1. verifying if any trigger has been invoked
+2. verifying if specified trigger has been invoked
+
+As for 1, here is a sample code excerpted from [ros2_subscription_examples/waitset_examples/src/timer_listener_triple_async.cpp at main · takam5f2/ros2_subscription_examples](https://github.com/takam5f2/ros2_subscription_examples/blob/main/waitset_examples/src/timer_listener_triple_async.cpp).
+
+```c++
+      auto wait_result = wait_set_.wait(std::chrono::milliseconds(0));
+      if (wait_result.kind() == rclcpp::WaitResultKind::Ready) {
+        RCLCPP_INFO(this->get_logger(), "wait_set tells that some subscription is ready");
+      } else {
+        RCLCPP_INFO(this->get_logger(), "wait_set tells that any subscription is not ready and return");
+        return;
+      }
+```
+
+In code above, it is verified whether any trigger has been invoked which is registered to `wait_set_` by `auto wait_result = wait_set_.wait(std::chrono::milliseconds(0))`.
+if `wait_result.kind() == rclcpp::WaitResultKind::Ready` is `true`, it indicates any trigger has been invoked.
+
+As for 2, here is a sample code excerpted from [ros2_subscription_examples/waitset_examples/src/timer_listener_triple_async.cpp at main · takam5f2/ros2_subscription_examples](https://github.com/takam5f2/ros2_subscription_examples/blob/main/waitset_examples/src/timer_listener_triple_async.cpp).
+
+```c++
+      for (size_t i = 0; i < subscriptions_num; i++) {
+        if (wait_result.get_wait_set().get_rcl_wait_set().subscriptions[i]) {
+          std_msgs::msg::String msg;
+          rclcpp::MessageInfo msg_info;
+          if (subscriptions_array_[i]->take(msg, msg_info)) {
+            RCLCPP_INFO(this->get_logger(), "Catch message via subscription[%ld]", i);
+            RCLCPP_INFO(this->get_logger(), "I heard: [%s]", msg.data.c_str());
+```
+
+In code above, `wait_result.get_wait_set().get_rcl_wait_set().subscriptions[i]` indicates whether each individual trigger has been invoked or not. The result is stored to `subscriptions` array. The order in `subscriptions` array is the same as the order in which triggers are registered.