Events executor implementation. More...

#include <rclcpp/experimental/executors/events_executor/events_executor.hpp>

Inheritance diagram for rclcpp::experimental::executors::EventsExecutor:

Collaboration diagram for rclcpp::experimental::executors::EventsExecutor:

[legend]

Public Member Functions
RCLCPP_PUBLIC	EventsExecutor (rclcpp::experimental::executors::EventsQueue::UniquePtr events_queue=std::make_unique< rclcpp::experimental::executors::SimpleEventsQueue >(), bool execute_timers_separate_thread=false, const rclcpp::ExecutorOptions &options=rclcpp::ExecutorOptions())
	Default constructor. See the default constructor for Executor. More...

virtual RCLCPP_PUBLIC	~EventsExecutor ()
	Default destructor.

RCLCPP_PUBLIC void	spin () override
	Events executor implementation of spin. More...

RCLCPP_PUBLIC void	spin_some (std::chrono::nanoseconds max_duration=std::chrono::nanoseconds(0)) override
	Events executor implementation of spin some. More...

RCLCPP_PUBLIC void	spin_all (std::chrono::nanoseconds max_duration) override
	Events executor implementation of spin all. More...

RCLCPP_PUBLIC void	add_node (rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node_ptr, bool notify=true) override
	Add a node to the executor. More...

RCLCPP_PUBLIC void	add_node (std::shared_ptr< rclcpp::Node > node_ptr, bool notify=true) override
	Convenience function which takes Node and forwards NodeBaseInterface. More...

RCLCPP_PUBLIC void	remove_node (rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node_ptr, bool notify=true) override
	Remove a node from the executor. More...

RCLCPP_PUBLIC void	remove_node (std::shared_ptr< rclcpp::Node > node_ptr, bool notify=true) override
	Convenience function which takes Node and forwards NodeBaseInterface. More...

RCLCPP_PUBLIC void	add_callback_group (rclcpp::CallbackGroup::SharedPtr group_ptr, rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node_ptr, bool notify=true) override
	Add a callback group to an executor. More...

RCLCPP_PUBLIC void	remove_callback_group (rclcpp::CallbackGroup::SharedPtr group_ptr, bool notify=true) override
	Remove callback group from the executor. More...

RCLCPP_PUBLIC std::vector< rclcpp::CallbackGroup::WeakPtr >	get_all_callback_groups () override
	Get callback groups that belong to executor. More...

RCLCPP_PUBLIC std::vector< rclcpp::CallbackGroup::WeakPtr >	get_manually_added_callback_groups () override
	Get callback groups that belong to executor. More...

RCLCPP_PUBLIC std::vector< rclcpp::CallbackGroup::WeakPtr >	get_automatically_added_callback_groups_from_nodes () override
	Get callback groups that belong to executor. More...

Public Member Functions inherited from rclcpp::Executor
RCLCPP_PUBLIC	Executor (const rclcpp::ExecutorOptions &options=rclcpp::ExecutorOptions())
	Default constructor. More...

virtual RCLCPP_PUBLIC	~Executor ()
	Default destructor.

template<typename RepT = int64_t, typename T = std::milli>
void	spin_node_once (rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node, std::chrono::duration< RepT, T > timeout=std::chrono::duration< RepT, T >(-1))
	Add a node to executor, execute the next available unit of work, and remove the node. More...

template<typename NodeT = rclcpp::Node, typename RepT = int64_t, typename T = std::milli>
void	spin_node_once (std::shared_ptr< NodeT > node, std::chrono::duration< RepT, T > timeout=std::chrono::duration< RepT, T >(-1))
	Convenience function which takes Node and forwards NodeBaseInterface.

virtual RCLCPP_PUBLIC void	spin_node_some (rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node)
	Add a node, complete all immediately available work, and remove the node. More...

virtual RCLCPP_PUBLIC void	spin_node_some (std::shared_ptr< rclcpp::Node > node)
	Convenience function which takes Node and forwards NodeBaseInterface.

virtual RCLCPP_PUBLIC void	spin_node_all (rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node, std::chrono::nanoseconds max_duration)
	Add a node, complete all immediately available work exhaustively, and remove the node. More...

virtual RCLCPP_PUBLIC void	spin_node_all (std::shared_ptr< rclcpp::Node > node, std::chrono::nanoseconds max_duration)
	Convenience function which takes Node and forwards NodeBaseInterface.

virtual RCLCPP_PUBLIC void	spin_once (std::chrono::nanoseconds timeout=std::chrono::nanoseconds(-1))
	Collect work once and execute the next available work, optionally within a duration. More...

template<typename FutureT , typename TimeRepT = int64_t, typename TimeT = std::milli>
FutureReturnCode	spin_until_future_complete (const FutureT &future, std::chrono::duration< TimeRepT, TimeT > timeout=std::chrono::duration< TimeRepT, TimeT >(-1))
	Spin (blocking) until the future is complete, it times out waiting, or rclcpp is interrupted. More...

virtual RCLCPP_PUBLIC void	cancel ()
	Cancel any running spin* function, causing it to return. More...

RCLCPP_PUBLIC bool	is_spinning ()
	Returns true if the executor is currently spinning. More...

Protected Member Functions
RCLCPP_PUBLIC void	spin_once_impl (std::chrono::nanoseconds timeout) override
	Internal implementation of spin_once.

RCLCPP_PUBLIC void	spin_some_impl (std::chrono::nanoseconds max_duration, bool exhaustive)
	Internal implementation of spin_some.

Protected Member Functions inherited from rclcpp::Executor
	Executor (const std::shared_ptr< rclcpp::Context > &context)
	Constructor that will not initialize any non-trivial members. More...

RCLCPP_PUBLIC void	spin_node_once_nanoseconds (rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node, std::chrono::nanoseconds timeout)
	Add a node to executor, execute the next available unit of work, and remove the node. More...

virtual RCLCPP_PUBLIC FutureReturnCode	spin_until_future_complete_impl (std::chrono::nanoseconds timeout, const std::function< std::future_status(std::chrono::nanoseconds wait_time)> &wait_for_future)
	Spin (blocking) until the future is complete, it times out waiting, or rclcpp is interrupted. More...

RCLCPP_PUBLIC void	spin_some_impl (std::chrono::nanoseconds max_duration, bool exhaustive)
	Collect work and execute available work, optionally within a duration. More...

RCLCPP_PUBLIC void	execute_any_executable (AnyExecutable &any_exec)
	Find the next available executable and do the work associated with it. More...

RCLCPP_PUBLIC void	collect_entities ()
	Gather all of the waitable entities from associated nodes and callback groups.

RCLCPP_PUBLIC void	wait_for_work (std::chrono::nanoseconds timeout=std::chrono::nanoseconds(-1))
	Block until more work becomes avilable or timeout is reached. More...

RCLCPP_PUBLIC bool	get_next_ready_executable (AnyExecutable &any_executable)
	Check for executable in ready state and populate union structure. More...

RCLCPP_PUBLIC bool	get_next_executable (AnyExecutable &any_executable, std::chrono::nanoseconds timeout=std::chrono::nanoseconds(-1))
	Wait for executable in ready state and populate union structure. More...

void	trigger_entity_recollect (bool notify)
	This function triggers a recollect of all entities that are registered to the executor. More...

rclcpp::WaitSet wait_set_	RCPPUTILS_TSA_GUARDED_BY (mutex_)
	WaitSet to be waited on.

std::optional< rclcpp::WaitResult< rclcpp::WaitSet > > wait_result_	RCPPUTILS_TSA_GUARDED_BY (mutex_)

rclcpp::executors::ExecutorEntitiesCollection current_collection_	RCPPUTILS_TSA_GUARDED_BY (mutex_)
	Hold the current state of the collection being waited on by the waitset.

std::shared_ptr< rclcpp::executors::ExecutorNotifyWaitable > current_notify_waitable_	RCPPUTILS_TSA_GUARDED_BY (mutex_)
	Hold the current state of the notify waitable being waited on by the waitset.

Friends
class	EventsExecutorEntitiesCollector

Additional Inherited Members
Static Protected Member Functions inherited from rclcpp::Executor
static RCLCPP_PUBLIC void	execute_subscription (rclcpp::SubscriptionBase::SharedPtr subscription)
	Run subscription executable. More...

static RCLCPP_PUBLIC void	execute_timer (rclcpp::TimerBase::SharedPtr timer, const std::shared_ptr< void > &data_ptr)
	Run timer executable. More...

static RCLCPP_PUBLIC void	execute_service (rclcpp::ServiceBase::SharedPtr service)
	Run service server executable. More...

static RCLCPP_PUBLIC void	execute_client (rclcpp::ClientBase::SharedPtr client)
	Run service client executable. More...

Protected Attributes inherited from rclcpp::Executor
std::atomic_bool	spinning
	Spinning state, used to prevent multi threaded calls to spin and to cancel blocking spins.

std::shared_ptr< rclcpp::GuardCondition >	interrupt_guard_condition_
	Guard condition for signaling the rmw layer to wake up for special events.

std::shared_ptr< rclcpp::GuardCondition >	shutdown_guard_condition_
	Guard condition for signaling the rmw layer to wake up for system shutdown.

std::mutex	mutex_

std::shared_ptr< rclcpp::Context >	context_
	The context associated with this executor.

std::shared_ptr< rclcpp::executors::ExecutorNotifyWaitable >	notify_waitable_
	Waitable containing guard conditions controlling the executor flow. More...

std::atomic_bool	entities_need_rebuild_

rclcpp::executors::ExecutorEntitiesCollector	collector_
	Collector used to associate executable entities from nodes and guard conditions.

rclcpp::OnShutdownCallbackHandle	shutdown_callback_handle_
	shutdown callback handle registered to Context

std::unique_ptr< ExecutorImplementation >	impl_
	Pointer to implementation.

Detailed Description

Events executor implementation.

This executor uses an events queue and a timers manager to execute entities from its associated nodes and callback groups. ROS 2 entities allow to set callback functions that are invoked when the entity is triggered or has work to do. The events-executor sets these callbacks such that they push an event into its queue.

This executor tries to reduce as much as possible the amount of maintenance operations. This allows to use customized EventsQueue classes to achieve different goals such as very low CPU usage, bounded memory requirement, determinism, etc.

The executor uses a weak ownership model and it locks entities only while executing their related events.

To run this executor: rclcpp::experimental::executors::EventsExecutor executor; executor.add_node(node); executor.spin(); executor.remove_node(node);

Definition at line 60 of file events_executor.hpp.

Constructor & Destructor Documentation

◆ EventsExecutor()

EventsExecutor::EventsExecutor	(	rclcpp::experimental::executors::EventsQueue::UniquePtr	events_queue = `std::make_unique< rclcpp::experimental::executors::SimpleEventsQueue>()`,
		bool	execute_timers_separate_thread = `false`,
		const rclcpp::ExecutorOptions &	options = `rclcpp::ExecutorOptions()`
	)

explicit

Default constructor. See the default constructor for Executor.

Parameters

[in]	events_queue	The queue used to store events.
[in]	execute_timers_separate_thread	If true, timers are executed in a separate thread. If false, timers are executed in the same thread as all other entities.
[in]	options	Options used to configure the executor.

Definition at line 27 of file events_executor.cpp.

References rclcpp::Executor::context_, rclcpp::Executor::interrupt_guard_condition_, and rclcpp::Executor::shutdown_guard_condition_.

Member Function Documentation

◆ add_callback_group()

void EventsExecutor::add_callback_group	(	rclcpp::CallbackGroup::SharedPtr	group_ptr,
		rclcpp::node_interfaces::NodeBaseInterface::SharedPtr	node_ptr,
		bool	notify = `true`
	)

overridevirtual

Add a callback group to an executor.

See also: rclcpp::Executor::add_callback_group

Reimplemented from rclcpp::Executor.

Definition at line 361 of file events_executor.cpp.

◆ add_node() [1/2]

void EventsExecutor::add_node	(	rclcpp::node_interfaces::NodeBaseInterface::SharedPtr	node_ptr,
		bool	notify = `true`
	)

overridevirtual

Add a node to the executor.

See also: rclcpp::Executor::add_node

Reimplemented from rclcpp::Executor.

Definition at line 240 of file events_executor.cpp.

Referenced by add_node().

Here is the caller graph for this function:

◆ add_node() [2/2]

void EventsExecutor::add_node	(	std::shared_ptr< rclcpp::Node >	node_ptr,
		bool	notify = `true`
	)

overridevirtual

Convenience function which takes Node and forwards NodeBaseInterface.

See also: rclcpp::EventsExecutor::add_node

Reimplemented from rclcpp::Executor.

Definition at line 253 of file events_executor.cpp.

References add_node().

Here is the call graph for this function:

◆ get_all_callback_groups()

std::vector< rclcpp::CallbackGroup::WeakPtr > EventsExecutor::get_all_callback_groups ( )

overridevirtual

Get callback groups that belong to executor.

See also: rclcpp::Executor::get_all_callback_groups()

Reimplemented from rclcpp::Executor.

Definition at line 390 of file events_executor.cpp.

◆ get_automatically_added_callback_groups_from_nodes()

std::vector< rclcpp::CallbackGroup::WeakPtr > EventsExecutor::get_automatically_added_callback_groups_from_nodes ( )

overridevirtual

Get callback groups that belong to executor.

See also: rclcpp::Executor::get_automatically_added_callback_groups_from_nodes()

Reimplemented from rclcpp::Executor.

Definition at line 404 of file events_executor.cpp.

◆ get_manually_added_callback_groups()

std::vector< rclcpp::CallbackGroup::WeakPtr > EventsExecutor::get_manually_added_callback_groups ( )

overridevirtual

Get callback groups that belong to executor.

See also: rclcpp::Executor::get_manually_added_callback_groups()

Reimplemented from rclcpp::Executor.

Definition at line 397 of file events_executor.cpp.

◆ remove_callback_group()

void EventsExecutor::remove_callback_group	(	rclcpp::CallbackGroup::SharedPtr	group_ptr,
		bool	notify = `true`
	)

overridevirtual

Remove callback group from the executor.

See also: rclcpp::Executor::remove_callback_group

Reimplemented from rclcpp::Executor.

Definition at line 377 of file events_executor.cpp.

◆ remove_node() [1/2]

void EventsExecutor::remove_node	(	rclcpp::node_interfaces::NodeBaseInterface::SharedPtr	node_ptr,
		bool	notify = `true`
	)

overridevirtual

Remove a node from the executor.

See also: rclcpp::Executor::remove_node

Reimplemented from rclcpp::Executor.

Definition at line 259 of file events_executor.cpp.

Referenced by remove_node().

Here is the caller graph for this function:

◆ remove_node() [2/2]

void EventsExecutor::remove_node	(	std::shared_ptr< rclcpp::Node >	node_ptr,
		bool	notify = `true`
	)

overridevirtual

Convenience function which takes Node and forwards NodeBaseInterface.

See also: rclcpp::Executor::remove_node

Reimplemented from rclcpp::Executor.

Definition at line 275 of file events_executor.cpp.

References remove_node().

Here is the call graph for this function:

◆ spin()

void EventsExecutor::spin ( )

overridevirtual

Events executor implementation of spin.

This function will block until work comes in, execute it, and keep blocking. It will only be interrupted by a CTRL-C (managed by the global signal handler).

Exceptions

std::runtime_error when spin() called while already spinning

Implements rclcpp::Executor.

Definition at line 108 of file events_executor.cpp.

References rclcpp::Executor::context_, rclcpp::ok(), and rclcpp::Executor::spinning.

Here is the call graph for this function:

◆ spin_all()

void EventsExecutor::spin_all ( std::chrono::nanoseconds max_duration )

overridevirtual

Events executor implementation of spin all.

This non-blocking function will execute timers and events until timeout or no more work available. If new ready-timers/events arrive while executing work available, they will be executed as long as the timeout hasn't expired.

Example: while(condition) { spin_all(); sleep(); // User should have some sync work or // sleep to avoid a 100% CPU usage }

Reimplemented from rclcpp::Executor.

Definition at line 135 of file events_executor.cpp.

References spin_some_impl().

Here is the call graph for this function:

◆ spin_some()

void EventsExecutor::spin_some ( std::chrono::nanoseconds max_duration = std::chrono::nanoseconds(0) )

overridevirtual

Events executor implementation of spin some.

This non-blocking function will execute the timers and events that were ready when this API was called, until timeout or no more work available. New ready-timers/events arrived while executing work, won't be taken into account here.

Example: while(condition) { spin_some(); sleep(); // User should have some sync work or // sleep to avoid a 100% CPU usage }

Reimplemented from rclcpp::Executor.

Definition at line 129 of file events_executor.cpp.

References spin_some_impl().

Here is the call graph for this function:

The documentation for this class was generated from the following files:

rclcpp/include/rclcpp/experimental/executors/events_executor/events_executor.hpp
rclcpp/src/rclcpp/experimental/executors/events_executor/events_executor.cpp

Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ EventsExecutor()

Member Function Documentation

◆ add_callback_group()

◆ add_node() [1/2]

◆ add_node() [2/2]

◆ get_all_callback_groups()

◆ get_automatically_added_callback_groups_from_nodes()

◆ get_manually_added_callback_groups()

◆ remove_callback_group()

◆ remove_node() [1/2]

◆ remove_node() [2/2]

◆ spin()

◆ spin_all()

◆ spin_some()