From e1cc880ead82b670e84d620e7996491a62d7b7c9 Mon Sep 17 00:00:00 2001 From: Tomoya Fujita Date: Thu, 26 Dec 2024 11:34:17 -0800 Subject: [PATCH] add explanation about component containers. Signed-off-by: Tomoya Fujita Co-authored-by: Christophe Bedard --- .../Intermediate/About-Composition.rst | 24 +++++++++++++++++ .../Concepts/Intermediate/About-Executors.rst | 2 ++ source/Tutorials/Intermediate/Composition.rst | 27 +++++++++++++++++++ 3 files changed, 53 insertions(+) diff --git a/source/Concepts/Intermediate/About-Composition.rst b/source/Concepts/Intermediate/About-Composition.rst index a6cbdb5dcc1..6ef546d0945 100644 --- a/source/Concepts/Intermediate/About-Composition.rst +++ b/source/Concepts/Intermediate/About-Composition.rst @@ -33,6 +33,30 @@ By making the process layout a deploy-time decision the user can choose between: Additionally ``ros2 launch`` can be used to automate these actions through specialized launch actions. +.. _ComponentContainer: + +Component Container +------------------- + +A component container is a host process that allows you to load and manage multiple components at runtime within the same process space. + +As of now, the following generic component container types are available: + +* `component_container `__ + + * The most generic component container that uses a single ``SingleThreadedExecutor`` to execute all components. + +* `component_container_mt `__ + + * Component container that uses a single ``MultiThreadedExecutor`` to execute the components. + +* `component_container_isolated `__ + + * Component container that uses a dedicated executor for each component: either ``SingleThreadedExecutor`` (default) or ``MultiThreadedExecutor``. + +For more information about the types of executors, see the :ref:`TypesOfExecutors`. +For more information about the options of each component container, see :ref:`ComponentContainerTypes` in the composition tutorial. + Writing a Component ------------------- diff --git a/source/Concepts/Intermediate/About-Executors.rst b/source/Concepts/Intermediate/About-Executors.rst index 0fe52187ec1..49d53b2f10f 100644 --- a/source/Concepts/Intermediate/About-Executors.rst +++ b/source/Concepts/Intermediate/About-Executors.rst @@ -59,6 +59,8 @@ The *wait set* is also used to detect when timers expire. The Single-Threaded Executor is also used by the container process for :doc:`components <./About-Composition>`, i.e. in all cases where nodes are created and executed without an explicit main function. +.. _TypesOfExecutors: + Types of Executors ------------------ diff --git a/source/Tutorials/Intermediate/Composition.rst b/source/Tutorials/Intermediate/Composition.rst index f8de6942a1b..f03d441ef1d 100644 --- a/source/Tutorials/Intermediate/Composition.rst +++ b/source/Tutorials/Intermediate/Composition.rst @@ -210,6 +210,33 @@ Advanced Topics Now that we have seen the basic operation of components, we can discuss a few more advanced topics. +.. _ComponentContainerTypes: + +Component container types +^^^^^^^^^^^^^^^^^^^^^^^^^ + +As introduced in :ref:`ComponentContainer`, there are a few component container types with different options. +You can choose the most appropriate component container type for your requirement. + +* ``component_container`` (No options / parameters available) + + .. code-block:: bash + + ros2 run rclcpp_components component_container + +* ``component_container_mt`` with ``MultiThreadedExecutor`` composed of 4 threads. + * ``thread_num`` parameter option is available to specify the number of threads in ``MultiThreadedExecutor``. + + .. code-block:: bash + + ros2 run rclcpp_components component_container_mt --ros-args -p thread_num:=4 + +* ``component_container_isolated`` with ``MultiThreadedExecutor`` for each component. + * ``--use_multi_threaded_executor`` argument specifies executor type used for each component to ``MultiThreadedExecutor``. + + .. code-block:: bash + + ros2 run rclcpp_components component_container_isolated --use_multi_threaded_executor Unloading components ^^^^^^^^^^^^^^^^^^^^