Class to monitor a set of nodes and callback groups for changes in entity membership. More...

#include <rclcpp/executors/executor_entities_collector.hpp>

Public Member Functions
RCLCPP_PUBLIC	ExecutorEntitiesCollector (std::shared_ptr< ExecutorNotifyWaitable > notify_waitable)
	Constructor. More...

RCLCPP_PUBLIC	~ExecutorEntitiesCollector ()
	Destructor.

bool	has_pending () const
	Indicate if the entities collector has pending additions or removals. More...

RCLCPP_PUBLIC void	add_node (rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node_ptr)
	Add a node to the entity collector. More...

RCLCPP_PUBLIC void	remove_node (rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node_ptr)
	Remove a node from the entity collector. More...

RCLCPP_PUBLIC void	add_callback_group (rclcpp::CallbackGroup::SharedPtr group_ptr)
	Add a callback group to the entity collector. More...

RCLCPP_PUBLIC void	remove_callback_group (rclcpp::CallbackGroup::SharedPtr group_ptr)
	Remove a callback group from the entity collector. More...

RCLCPP_PUBLIC std::vector< rclcpp::CallbackGroup::WeakPtr >	get_all_callback_groups () const
	Get all callback groups known to this entity collector. More...

RCLCPP_PUBLIC std::vector< rclcpp::CallbackGroup::WeakPtr >	get_manually_added_callback_groups () const
	Get manually-added callback groups known to this entity collector. More...

RCLCPP_PUBLIC std::vector< rclcpp::CallbackGroup::WeakPtr >	get_automatically_added_callback_groups () const
	Get automatically-added callback groups known to this entity collector. More...

RCLCPP_PUBLIC void	update_collections ()
	Update the underlying collections. More...

Protected Types
using	NodeCollection = std::set< rclcpp::node_interfaces::NodeBaseInterface::WeakPtr, std::owner_less< rclcpp::node_interfaces::NodeBaseInterface::WeakPtr > >

using	CallbackGroupCollection = std::set< rclcpp::CallbackGroup::WeakPtr, std::owner_less< rclcpp::CallbackGroup::WeakPtr > >

using	WeakNodesToGuardConditionsMap = std::map< rclcpp::node_interfaces::NodeBaseInterface::WeakPtr, rclcpp::GuardCondition::WeakPtr, std::owner_less< rclcpp::node_interfaces::NodeBaseInterface::WeakPtr > >

using	WeakGroupsToGuardConditionsMap = std::map< rclcpp::CallbackGroup::WeakPtr, rclcpp::GuardCondition::WeakPtr, std::owner_less< rclcpp::CallbackGroup::WeakPtr > >

Protected Member Functions
RCLCPP_PUBLIC NodeCollection::iterator	remove_weak_node (NodeCollection::iterator weak_node) RCPPUTILS_TSA_REQUIRES(mutex_)
	Implementation of removing a node from the collector. More...

RCLCPP_PUBLIC CallbackGroupCollection::iterator	remove_weak_callback_group (CallbackGroupCollection::iterator weak_group_it, CallbackGroupCollection &collection) RCPPUTILS_TSA_REQUIRES(mutex_)
	Implementation of removing a callback group from the collector. More...

RCLCPP_PUBLIC void	add_callback_group_to_collection (rclcpp::CallbackGroup::SharedPtr group_ptr, CallbackGroupCollection &collection) RCPPUTILS_TSA_REQUIRES(mutex_)
	Implementation of adding a callback group. More...

RCLCPP_PUBLIC void	process_queues () RCPPUTILS_TSA_REQUIRES(mutex_)
	Iterate over queued added/remove nodes and callback_groups.

RCLCPP_PUBLIC void	add_automatically_associated_callback_groups (const NodeCollection &nodes_to_check) RCPPUTILS_TSA_REQUIRES(mutex_)

RCLCPP_PUBLIC void	prune_invalid_nodes_and_groups () RCPPUTILS_TSA_REQUIRES(mutex_)
	Check all nodes and group for expired weak pointers and remove them.

CallbackGroupCollection manually_added_groups_	RCPPUTILS_TSA_GUARDED_BY (mutex_)
	Callback groups that were added via `add_callback_group`

CallbackGroupCollection automatically_added_groups_	RCPPUTILS_TSA_GUARDED_BY (mutex_)
	Callback groups that were added by their association with added nodes.

NodeCollection weak_nodes_	RCPPUTILS_TSA_GUARDED_BY (mutex_)
	nodes that are associated with the executor

WeakNodesToGuardConditionsMap weak_nodes_to_guard_conditions_	RCPPUTILS_TSA_GUARDED_BY (mutex_)
	Track guard conditions associated with added nodes.

WeakGroupsToGuardConditionsMap weak_groups_to_guard_conditions_	RCPPUTILS_TSA_GUARDED_BY (mutex_)
	Track guard conditions associated with added callback groups.

NodeCollection pending_added_nodes_	RCPPUTILS_TSA_GUARDED_BY (mutex_)
	nodes that have been added since the last update.

NodeCollection pending_removed_nodes_	RCPPUTILS_TSA_GUARDED_BY (mutex_)
	nodes that have been removed since the last update.

CallbackGroupCollection pending_manually_added_groups_	RCPPUTILS_TSA_GUARDED_BY (mutex_)
	callback groups that have been added since the last update.

CallbackGroupCollection pending_manually_removed_groups_	RCPPUTILS_TSA_GUARDED_BY (mutex_)
	callback groups that have been removed since the last update.

Protected Attributes
std::mutex	mutex_
	mutex to protect collections and pending queues

std::shared_ptr< ExecutorNotifyWaitable >	notify_waitable_
	Waitable to add guard conditions to.

Detailed Description

Class to monitor a set of nodes and callback groups for changes in entity membership.

This is to be used with an executor to track the membership of various nodes, groups, and entities (timers, subscriptions, clients, services, etc) and report status to the executor.

In general, users will add either nodes or callback groups to an executor. Each node may have callback groups that are automatically associated with executors, or callback groups that must be manually associated with an executor.

This object tracks both types of callback groups as well as nodes that have been previously added to the executor. When a new callback group is added/removed or new entities are added/removed, the corresponding node or callback group will signal this to the executor so that the entity collection may be rebuilt according to that executor's implementation.

Definition at line 56 of file executor_entities_collector.hpp.

Constructor & Destructor Documentation

◆ ExecutorEntitiesCollector()

rclcpp::executors::ExecutorEntitiesCollector::ExecutorEntitiesCollector ( std::shared_ptr< ExecutorNotifyWaitable > notify_waitable )

explicit

Constructor.

Parameters

[in] notify_waitable Waitable that is used to signal to the executor when nodes or callback groups have been added or removed.

Definition at line 26 of file executor_entities_collector.cpp.

Member Function Documentation

◆ add_automatically_associated_callback_groups()

void rclcpp::executors::ExecutorEntitiesCollector::add_automatically_associated_callback_groups ( const NodeCollection & nodes_to_check )

protected

Check a collection of nodes and add any new callback_groups that are set to be automatically associated via the node.

Definition at line 382 of file executor_entities_collector.cpp.

Referenced by process_queues(), and update_collections().

Here is the caller graph for this function:

◆ add_callback_group()

void rclcpp::executors::ExecutorEntitiesCollector::add_callback_group ( rclcpp::CallbackGroup::SharedPtr group_ptr )

Add a callback group to the entity collector.

Parameters

[in] group_ptr a shared pointer that points to a callback group

Exceptions

std::runtime_error if the callback_group is associated with an executor

Definition at line 136 of file executor_entities_collector.cpp.

References mutex_, and notify_waitable_.

Referenced by rclcpp::Executor::add_callback_group().

Here is the caller graph for this function:

◆ add_callback_group_to_collection()

void rclcpp::executors::ExecutorEntitiesCollector::add_callback_group_to_collection	(	rclcpp::CallbackGroup::SharedPtr	group_ptr,
		CallbackGroupCollection &	collection
	)

protected

Implementation of adding a callback group.

Parameters

[in]	group_ptr	the group to add
[in]	collection	the collection to add the group to

Definition at line 290 of file executor_entities_collector.cpp.

References notify_waitable_.

Referenced by process_queues().

Here is the caller graph for this function:

◆ add_node()

void rclcpp::executors::ExecutorEntitiesCollector::add_node ( rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node_ptr )

Add a node to the entity collector.

Parameters

[in] node_ptr a shared pointer that points to a node base interface

Exceptions

std::runtime_error if the node is associated with an executor

Definition at line 86 of file executor_entities_collector.cpp.

References mutex_.

Referenced by rclcpp::Executor::add_node().

Here is the caller graph for this function:

◆ get_all_callback_groups()

std::vector< rclcpp::CallbackGroup::WeakPtr > rclcpp::executors::ExecutorEntitiesCollector::get_all_callback_groups ( ) const

Get all callback groups known to this entity collector.

This will include manually added and automatically added (node associated) groups

Returns: vector of all callback groups

Definition at line 190 of file executor_entities_collector.cpp.

References mutex_.

Referenced by rclcpp::Executor::collect_entities(), rclcpp::Executor::get_all_callback_groups(), and rclcpp::Executor::wait_for_work().

Here is the caller graph for this function:

◆ get_automatically_added_callback_groups()

std::vector< rclcpp::CallbackGroup::WeakPtr > rclcpp::executors::ExecutorEntitiesCollector::get_automatically_added_callback_groups ( ) const

Get automatically-added callback groups known to this entity collector.

This will include callback groups that are associated with nodes added via add_node

Returns: vector of automatically-added callback groups

Definition at line 215 of file executor_entities_collector.cpp.

References mutex_.

Referenced by rclcpp::Executor::get_automatically_added_callback_groups_from_nodes().

Here is the caller graph for this function:

◆ get_manually_added_callback_groups()

std::vector< rclcpp::CallbackGroup::WeakPtr > rclcpp::executors::ExecutorEntitiesCollector::get_manually_added_callback_groups ( ) const

Get manually-added callback groups known to this entity collector.

This will include callback groups that have been added via add_callback_group

Returns: vector of manually-added callback groups

Definition at line 204 of file executor_entities_collector.cpp.

References mutex_.

Referenced by rclcpp::Executor::get_manually_added_callback_groups().

Here is the caller graph for this function:

◆ has_pending()

bool rclcpp::executors::ExecutorEntitiesCollector::has_pending ( ) const

Indicate if the entities collector has pending additions or removals.

Returns: true if there are pending additions or removals

Definition at line 76 of file executor_entities_collector.cpp.

References mutex_.

◆ remove_callback_group()

void rclcpp::executors::ExecutorEntitiesCollector::remove_callback_group ( rclcpp::CallbackGroup::SharedPtr group_ptr )

Remove a callback group from the entity collector.

Parameters

[in] group_ptr a shared pointer that points to a callback group

Exceptions

std::runtime_error	if the callback_group is not associated with an executor
std::runtime_error	if the callback_group is not associated with this executor

TODO(mjcarroll): The callback groups, being created by a node, should never outlive the node. Since we haven't historically enforced this, turning this on may cause previously-functional code to fail. Consider re-enablng this check (along with corresponding CallbackGroup::has_valid_node), when we can guarantee node/group lifetimes. if (!group_ptr->has_valid_node()) { throw std::runtime_error("Node must not be deleted before its callback group(s)."); }

Definition at line 161 of file executor_entities_collector.cpp.

References mutex_.

Referenced by rclcpp::Executor::remove_callback_group().

Here is the caller graph for this function:

◆ remove_node()

void rclcpp::executors::ExecutorEntitiesCollector::remove_node ( rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node_ptr )

Remove a node from the entity collector.

Parameters

[in] node_ptr a shared pointer that points to a node base interface

Exceptions

std::runtime_error	if the node is associated with an executor
std::runtime_error	if the node is associated with this executor

Definition at line 111 of file executor_entities_collector.cpp.

References mutex_.

Referenced by rclcpp::Executor::remove_node().

Here is the caller graph for this function:

◆ remove_weak_callback_group()

ExecutorEntitiesCollector::CallbackGroupCollection::iterator rclcpp::executors::ExecutorEntitiesCollector::remove_weak_callback_group	(	CallbackGroupCollection::iterator	weak_group_it,
		CallbackGroupCollection &	collection
	)

protected

Implementation of removing a callback group from the collector.

This will disassociate the callback group from the collector

This takes and returns an iterator so it may be used as:

it = remove_weak_callback_group(it);

Parameters

[in]	weak_group_it	iterator to the weak group to be removed
[in]	collection	the collection to remove the group from (manually or automatically added)

Returns: Valid updated iterator in the same collection

TODO(mjcarroll): The callback groups, being created by a node, should never outlive the node. Since we haven't historically enforced this, turning this on may cause previously-functional code to fail. Consider re-enablng this check (along with corresponding CallbackGroup::has_valid_node), when we can guarantee node/group lifetimes. if (!group_ptr->has_valid_node()) { throw std::runtime_error("Node must not be deleted before its callback group(s)."); }

Definition at line 256 of file executor_entities_collector.cpp.

References notify_waitable_.

Referenced by process_queues(), and ~ExecutorEntitiesCollector().

Here is the caller graph for this function:

◆ remove_weak_node()

ExecutorEntitiesCollector::NodeCollection::iterator rclcpp::executors::ExecutorEntitiesCollector::remove_weak_node ( NodeCollection::iterator weak_node )

protected

Implementation of removing a node from the collector.

This will disassociate the node from the collector and remove any automatically-added callback groups

This takes and returns an iterator so it may be used as:

it = remove_weak_node(it);

Parameters

[in] weak_node iterator to the weak node to be removed