add explanation about component containers. (#4902) (#4919)

Signed-off-by: Tomoya Fujita <[email protected]>
Co-authored-by: Christophe Bedard <[email protected]>
(cherry picked from commit 994c0d9)

Co-authored-by: Tomoya Fujita <[email protected]>

Author: mergify[bot]

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 <https://github.com/ros2/rclcpp/blob/{REPOS_FILE_BRANCH}/rclcpp_components/src/component_container.cpp>`__
+
+  * The most generic component container that uses a single ``SingleThreadedExecutor`` to execute all components.
+
+* `component_container_mt <https://github.com/ros2/rclcpp/blob/{REPOS_FILE_BRANCH}/rclcpp_components/src/component_container_mt.cpp>`__
+
+  * Component container that uses a single ``MultiThreadedExecutor`` to execute the components.
+
+* `component_container_isolated <https://github.com/ros2/rclcpp/blob/{REPOS_FILE_BRANCH}/rclcpp_components/src/component_container_isolated.cpp>`__
+
+  * 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
 -------------------
 

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
 ------------------
 

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
 ^^^^^^^^^^^^^^^^^^^^