Add in additional info about using intra-process comms. (ros2#2225)

clalancette · web-flow · commit 16860488d5b8 · 2022-01-19T15:03:25.000-05:00
* Add in additional info about using intra-process comms.

Signed-off-by: Chris Lalancette &lt;clalancette@openrobotics.org&gt;
diff --git a/source/How-To-Guides.rst b/source/How-To-Guides.rst
@@ -26,6 +26,7 @@ If you are new and looking to learn the ropes, start with the :doc:`Tutorials <T
    How-To-Guides/Ament-CMake-Python-Documentation
    How-To-Guides/Launch-files-migration-guide
    How-To-Guides/Launch-file-different-formats
+   How-To-Guides/Launching-composable-nodes
    How-To-Guides/Parameters-YAML-files-migration-guide
    How-To-Guides/Node-arguments
    How-To-Guides/Sync-Vs-Async
diff --git a/source/How-To-Guides/Launching-composable-nodes.rst b/source/How-To-Guides/Launching-composable-nodes.rst
@@ -0,0 +1,156 @@
+Using ROS 2 launch to launch composable nodes
+=============================================
+
+.. contents:: Table of Contents
+   :depth: 1
+   :local:
+
+In the :doc:`Composition tutorial <../Tutorials/Composition>`, you learned about composable nodes and how to use them from the command-line.
+In the :doc:`Launch tutorials <../Tutorials/Launch/Launch-Main>`, you learned about launch files and how to use them to manage multiple nodes.
+
+This guide will combine the above two topics and teach you how to write launch files for composable nodes.
+
+Setup
+-----
+
+See the :doc:`installation instructions <../Installation>` for details on installing ROS 2.
+
+If you've installed ROS 2 from packages, ensure that you have ``ros-{DISTRO}-image-tools`` installed.
+If you downloaded the archive or built ROS 2 from source, it will already be part of the installation.
+
+Launch file examples
+--------------------
+
+Below is a launch file that launches composable nodes in Python, XML, and YAML.
+The launch files all do the following:
+
+* Instantiate a cam2image composable node with remappings, custom parameters, and extra arguments
+* Instantiate a showimage composable node with remappings, custom parameters, and extra arguments
+
+.. tabs::
+
+  .. group-tab:: Python
+
+    .. code-block:: python
+
+      import launch
+      from launch_ros.actions import ComposableNodeContainer
+      from launch_ros.descriptions import ComposableNode
+
+
+      def generate_launch_description():
+          """Generate launch description with multiple components."""
+          container = ComposableNodeContainer(
+                  name='image_container',
+                  namespace='',
+                  package='rclcpp_components',
+                  executable='component_container',
+                  composable_node_descriptions=[
+                      ComposableNode(
+                          package='image_tools',
+                          plugin='image_tools::Cam2Image',
+                          name='cam2image',
+                          remappings=[('/image', '/burgerimage')],
+                          parameters=[{'width': 320, 'height': 240, 'burger_mode': True, 'history': 'keep_last'}],
+                          extra_arguments=[{'use_intra_process_comms': True}]),
+                      ComposableNode(
+                          package='image_tools',
+                          plugin='image_tools::ShowImage',
+                          name='showimage',
+                          remappings=[('/image', '/burgerimage')],
+                          parameters=[{'history': 'keep_last'}],
+                          extra_arguments=[{'use_intra_process_comms': True}])
+                  ],
+                  output='both',
+          )
+
+          return launch.LaunchDescription([container])
+
+  .. group-tab:: XML
+
+    .. code-block:: xml
+
+      <launch>
+          <node_container pkg="rclcpp_components" exec="component_container" name="image_container" namespace="">
+              <composable_node pkg="image_tools" plugin="image_tools::Cam2Image" name="cam2image" namespace="">
+                  <remap from="/image" to="/burgerimage" />
+                  <param name="width" value="320" />
+                  <param name="height" value="240" />
+                  <param name="burger_mode" value="true" />
+                  <param name="history" value="keep_last" />
+                  <extra_arg name="use_intra_process_comms" value="true" />
+              </composable_node>
+              <composable_node pkg="image_tools" plugin="image_tools::ShowImage" name="showimage" namespace="">
+                  <remap from="/image" to="/burgerimage" />
+                  <param name="history" value="keep_last" />
+                  <extra_arg name="use_intra_process_comms" value="true" />
+              </composable_node>
+          </node_container>
+      </launch>
+
+  .. group-tab:: YAML
+
+    .. code-block:: yaml
+
+      launch:
+
+          - node_container:
+              pkg: rclcpp_components
+              exec: component_container
+              name: image_container
+              namespace: ''
+              composable_node:
+                  -   pkg: image_tools
+                      plugin: image_tools::Cam2Image
+                      name: cam2image
+                      namespace: ''
+                      remap:
+                          - from: /image
+                            to: /burgerimage
+                      param:
+                          - name: width
+                            value: 320
+                          - name: height
+                            value: 240
+                          - name: burger_mode
+                            value: true
+                          - name: history
+                            value: keep_last
+                      extra_arg:
+                          - name: use_intra_process_comms
+                            value: 'true'
+
+                  -   pkg: image_tools
+                      plugin: image_tools::ShowImage
+                      name: showimage
+                      namespace: ''
+                      remap:
+                          - from: /image
+                            to: /burgerimage
+                      param:
+                          - name: history
+                            value: keep_last
+                      extra_arg:
+                          - name: use_intra_process_comms
+                            value: 'true'
+
+Using the Launch files from the command-line
+--------------------------------------------
+
+Any of the launch files above can be run with ``ros2 launch``.
+Copy the data into a local file, and then run:
+
+.. code-block:: console
+
+  ros2 launch <path_to_launch_file>
+
+Intra-process communications
+----------------------------
+
+All of the above examples use an extra argument to setup intra-process communication between the nodes.
+For more information on what intra-process communications are, see the :doc:`intra-process comms tutorial <../Tutorials/Intra-Process-Communication>`.
+
+Python, XML, or YAML: Which should I use?
+-----------------------------------------
+
+See the discussion in :doc:`Launch-file-different-formats` for more information.
diff --git a/source/Tutorials/Composition.rst b/source/Tutorials/Composition.rst
@@ -12,7 +12,7 @@ Composing multiple nodes in a single process
 Background
 ----------
 
-See the `conceptual article <../Concepts/About-Composition>`.
+See the :doc:`conceptual article <../Concepts/About-Composition>`.
 
 Run the demos
 -------------
@@ -269,6 +269,27 @@ The corresponding entries appear in ``ros2 component list``:
 
    Namespace remappings of the container do not affect loaded components.
 
+Passing parameter values into components
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``ros2 component load`` command-line supports passing arbitrary parameters to the node as it is constructed.
+This functionality can be used as follows:
+
+.. code-block:: bash
+
+   $ ros2 component load /ComponentManager image_tools image_tools::Cam2Image -p burger_mode:=true
+
+Passing additional arguments into components
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``ros2 component load`` command-line supports passing particular options to the component manager for use when constructing the node.
+As of now, the only command-line option that is supported is to instantiate a node using intra-process communication.
+This functionality can be used as follows:
+
+.. code-block:: bash
+
+   $ ros2 component load /ComponentManager composition composition::Talker -e use_intra_process_comms:=true
+
 Composable nodes as shared libraries
 ------------------------------------
 
diff --git a/source/Tutorials/Intra-Process-Communication.rst b/source/Tutorials/Intra-Process-Communication.rst
@@ -19,23 +19,13 @@ In ROS 2 we aim to improve on the design of Nodelets by addressing some fundamen
 
 In this demo we'll be highlighting how nodes can be composed manually, by defining the nodes separately but combining them in different process layouts without changing the node's code or limiting its abilities.
 
-Build the demos
----------------
+Installing the demos
+--------------------
 
-These demos should work on any of the three major OSs (Windows, Mac, or Linux).
-Some of them do require OpenCV to have been installed.
+See the :doc:`installation instructions <../Installation>` for details on installing ROS 2.
 
-Using the pre-built binaries
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you've installed the binaries, simply source the ROS 2 setup file and then skip down to any of the individual demos to see how to run them.
-
-Building from source
-^^^^^^^^^^^^^^^^^^^^
-
-Make sure you have OpenCV installed and then follow the source instructions.
-You can find the from source instructions linked from the main `ros2 installation page <../Installation>`.
-Once built source the setup file and continue down to one of the specific demos to read about them and for instructions on how to run them.
+If you've installed ROS 2 from packages, ensure that you have ``ros-{DISTRO}-intra-process-demo`` installed.
+If you downloaded the archive or built ROS 2 from source, it will already be part of the installation.
 
 Running and understanding the demos
 -----------------------------------
@@ -274,7 +264,7 @@ To test those expectations, let's run it:
 
 .. code-block:: bash
 
-   % ros2 run intra_process_demo cyclic_pipeline
+   $ ros2 run intra_process_demo cyclic_pipeline
    Published first message with value:  42, and address: 0x7fd2ce0a2bc0
    Received message with value:         42, and address: 0x7fd2ce0a2bc0
      sleeping for 1 second...
@@ -307,14 +297,16 @@ The image pipeline demo
 
 In this demo we'll use OpenCV to capture, annotate, and then view images.
 
-Note for macOS users: If these examples do not work or you receive an error like ``ddsi_conn_write failed -1`` then you'll need to increase your system wide UDP packet size:
+.. note::
 
-.. code-block:: bash
+  If you are on macOS and these examples do not work or you receive an error like ``ddsi_conn_write failed -1``, then you'll need to increase your system wide UDP packet size:
 
-   $ sudo sysctl -w net.inet.udp.recvspace=209715
-   $ sudo sysctl -w net.inet.udp.maxdgram=65500
+  .. code-block:: bash
 
-These changes will not persist after a reboot.
+    $ sudo sysctl -w net.inet.udp.recvspace=209715
+    $ sudo sysctl -w net.inet.udp.maxdgram=65500
+
+  These changes will not persist after a reboot.
 
 Simple pipeline
 ~~~~~~~~~~~~~~~
@@ -394,38 +386,3 @@ One other important thing to get right is to avoid interruption of the intra pro
 
 
 It's hard to pause both images at the same time so the images may not line up, but the important thing to notice is that the ``image_pipeline_all_in_one`` image view shows the same address for each step. This means that the intra process zero-copy is preserved even when an external view is subscribed as well. You can also see that the interprocess image view has different process IDs for the first two lines of text and the process ID of the standalone image viewer in the third line of text.
-
-Looking forward
----------------
-
-These demos are the foundation for some cool new features on which we're actively working, but right now some things are missing.
-
-Room for Improvement
-^^^^^^^^^^^^^^^^^^^^
-
-Let's start by looking at what we at OSRF know we can do better or differently and move on from there.
-
-Performance, Performance, Performance
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This is a very rough first draft. There is a lot of room for improvement, even beyond what has been enumerated above. We'll start to improve performance as we dig into the details of the system, build up a better understanding of exactly what our middleware vendors are doing, and try alternative strategies for implementing intra process.
-
-Latching
-~~~~~~~~
-
-We haven't fully implemented the concept of latching yet, but it's very likely we'll need to adjust the implementation of the intra process manager to account for the fact that late intra process subscriptions should be delivered to as well. There are several options on how to do that, and we'll do some testing and figure out what to do in the near future.
-
-Beyond Pub/Sub
-~~~~~~~~~~~~~~
-
-We've not done any of this with Services, Parameters, or Actions, but we will.
-
-Type Masquerading
-~~~~~~~~~~~~~~~~~
-
-This is one of the coolest upcoming features that we didn't get to in this demo.
-Imagine the image pipeline demo above, but rather than passing ``sensor_msgs/Image``\ s around, you're publishing and subscribing to ``cv::Mat`` objects. This exists in ROS 1, see: https://wiki.ros.org/roscpp/Overview/MessagesSerializationAndAdaptingTypes
-
-In ROS 1, this is accomplished by serializing/deserializing the third party type when handling it. This means that with intra process you'll be serializing when passing it between nodelets. But in ROS 2 we want to do it in the most performant way possible. Similar to how these demos have been demonstrating that an instance of a message can be used through the whole pipeline in certain cases, we'd like to do the same with third party types. So conceivably you could have the image pipeline with a single ``cv::Mat`` which never gets copied by the middleware. To do this requires some additional intelligence in the intra process manager, but we've already got a design and some proof of concepts in the works.
-
-Given these features, hopefully there will come a point where you can trust the middleware to handle your data as efficiently as is possible. This will allow you to write performant algorithms without sacrificing modularity or introspection!
