From 9e99f3d446b8b1bd19ea5316e02c2cc069f08cd0 Mon Sep 17 00:00:00 2001 From: Michael Carroll Date: Mon, 22 May 2023 15:54:41 -0500 Subject: [PATCH 1/4] Add EventsExecutor release notes Signed-off-by: Michael Carroll --- source/Releases/Release-Iron-Irwini.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/source/Releases/Release-Iron-Irwini.rst b/source/Releases/Release-Iron-Irwini.rst index b93bc8af62..485f9c6a29 100644 --- a/source/Releases/Release-Iron-Irwini.rst +++ b/source/Releases/Release-Iron-Irwini.rst @@ -232,6 +232,29 @@ To make this a bit better, there is now a new ``NodeInterfaces`` class that can There are examples on how to use this in https://github.com/ros2/rclcpp/pull/2041. +Introduction of a new executor type: the Events Executor +"""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +The ``EventsExecutor`` from iRobot has been merged into the main ``rclcpp`` codebase. +This alternative executor implementation uses event-driven callbacks from the middleware implementations to fire callbacks at the ``rclcpp`` layer. +In addition to the push-based model, the `EventsExecutor` also moves timer management into a separate thread, which can allow for more accurate results and lower overhead, especially with many timers. + +The ``EventsExecutor`` has a substantial set of documentation and use-in-practice that make a strong candidate for inclusion the the ``rclcpp`` codebase. +For information about the initial implementation proposal as well as performance benchmarks, see https://discourse.ros.org/t/ros2-middleware-change-proposal/15863. +For more information about the design, see the design PR: https://github.com/ros2/design/pull/305. + +Since the API is the same, trying the ``EventsExecutor`` is as straighforward as replacing your current Execotr implmentation (eg. ``SingleThreadedExecutor``): + +.. code-block:: C++ + + #include + using rclcpp::experimental::executors::EventsExecutor; + + EventsExecutor executor; + executor.add_node(node); + executor.spin(); + + ``rclpy`` ^^^^^^^^^ From 238967483600bd61783892547d54db780aefca30 Mon Sep 17 00:00:00 2001 From: Michael Carroll Date: Mon, 22 May 2023 15:58:46 -0500 Subject: [PATCH 2/4] Apply suggestions from code review Signed-off-by: Michael Carroll Co-authored-by: Christophe Bedard --- source/Releases/Release-Iron-Irwini.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/Releases/Release-Iron-Irwini.rst b/source/Releases/Release-Iron-Irwini.rst index 485f9c6a29..fff2e85320 100644 --- a/source/Releases/Release-Iron-Irwini.rst +++ b/source/Releases/Release-Iron-Irwini.rst @@ -239,11 +239,11 @@ The ``EventsExecutor`` from iRobot has been merged into the main ``rclcpp`` code This alternative executor implementation uses event-driven callbacks from the middleware implementations to fire callbacks at the ``rclcpp`` layer. In addition to the push-based model, the `EventsExecutor` also moves timer management into a separate thread, which can allow for more accurate results and lower overhead, especially with many timers. -The ``EventsExecutor`` has a substantial set of documentation and use-in-practice that make a strong candidate for inclusion the the ``rclcpp`` codebase. +The ``EventsExecutor`` has a substantial set of documentation and use-in-practice that make it a strong candidate for inclusion in the ``rclcpp`` codebase. For information about the initial implementation proposal as well as performance benchmarks, see https://discourse.ros.org/t/ros2-middleware-change-proposal/15863. For more information about the design, see the design PR: https://github.com/ros2/design/pull/305. -Since the API is the same, trying the ``EventsExecutor`` is as straighforward as replacing your current Execotr implmentation (eg. ``SingleThreadedExecutor``): +Since the API is the same, trying the ``EventsExecutor`` is as straightforward as replacing your current Executor implementation (eg. ``SingleThreadedExecutor``): .. code-block:: C++ From 19fb06e8f751aab14cbcd08282331afba02daf70 Mon Sep 17 00:00:00 2001 From: Michael Carroll Date: Mon, 22 May 2023 17:34:39 -0500 Subject: [PATCH 3/4] Add note about experimental --- source/Releases/Release-Iron-Irwini.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/Releases/Release-Iron-Irwini.rst b/source/Releases/Release-Iron-Irwini.rst index fff2e85320..4b01b86a59 100644 --- a/source/Releases/Release-Iron-Irwini.rst +++ b/source/Releases/Release-Iron-Irwini.rst @@ -254,6 +254,9 @@ Since the API is the same, trying the ``EventsExecutor`` is as straightforward a executor.add_node(node); executor.spin(); +**Note** The ``EventsExecutor`` and ``TimersManager`` are currently in the `experimental` namespace. +While it has been used as a standalone implementation for some time https://github.com/irobot-ros/events-executor, it was decided to use the `experimental` namespace for at least one release to give latitude in changing the API within the release. +Use caution as it will not be subject to the same API/ABI guarantees that the non-experimental code has. ``rclpy`` ^^^^^^^^^ From b37227e99258ec41fbef18a106235fca568ee51b Mon Sep 17 00:00:00 2001 From: Chris Lalancette Date: Tue, 23 May 2023 08:08:17 -0400 Subject: [PATCH 4/4] Fix RST markup. Signed-off-by: Chris Lalancette --- source/Releases/Release-Iron-Irwini.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/Releases/Release-Iron-Irwini.rst b/source/Releases/Release-Iron-Irwini.rst index 4b01b86a59..341ef0c2ac 100644 --- a/source/Releases/Release-Iron-Irwini.rst +++ b/source/Releases/Release-Iron-Irwini.rst @@ -237,7 +237,7 @@ Introduction of a new executor type: the Events Executor The ``EventsExecutor`` from iRobot has been merged into the main ``rclcpp`` codebase. This alternative executor implementation uses event-driven callbacks from the middleware implementations to fire callbacks at the ``rclcpp`` layer. -In addition to the push-based model, the `EventsExecutor` also moves timer management into a separate thread, which can allow for more accurate results and lower overhead, especially with many timers. +In addition to the push-based model, the ``EventsExecutor`` also moves timer management into a separate thread, which can allow for more accurate results and lower overhead, especially with many timers. The ``EventsExecutor`` has a substantial set of documentation and use-in-practice that make it a strong candidate for inclusion in the ``rclcpp`` codebase. For information about the initial implementation proposal as well as performance benchmarks, see https://discourse.ros.org/t/ros2-middleware-change-proposal/15863. @@ -254,8 +254,8 @@ Since the API is the same, trying the ``EventsExecutor`` is as straightforward a executor.add_node(node); executor.spin(); -**Note** The ``EventsExecutor`` and ``TimersManager`` are currently in the `experimental` namespace. -While it has been used as a standalone implementation for some time https://github.com/irobot-ros/events-executor, it was decided to use the `experimental` namespace for at least one release to give latitude in changing the API within the release. +**Note** The ``EventsExecutor`` and ``TimersManager`` are currently in the ``experimental`` namespace. +While it has been used as a standalone implementation for some time https://github.com/irobot-ros/events-executor, it was decided to use the ``experimental`` namespace for at least one release to give latitude in changing the API within the release. Use caution as it will not be subject to the same API/ABI guarantees that the non-experimental code has. ``rclpy``