ROS 2 rclcpp + rcl - lyrical  lyrical
ROS 2 C++ Client Library with ROS Client Library
Classes | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
rclcpp::executors::EventsCBGExecutor Class Reference
Inheritance diagram for rclcpp::executors::EventsCBGExecutor:
Inheritance graph
[legend]
Collaboration diagram for rclcpp::executors::EventsCBGExecutor:
Collaboration graph
[legend]

Classes

struct  CallbackGroupData
 

Public Member Functions

RCLCPP_PUBLIC EventsCBGExecutor (const rclcpp::ExecutorOptions &options=rclcpp::ExecutorOptions(), size_t number_of_threads=0, std::chrono::nanoseconds timeout=std::chrono::nanoseconds(-1))
 
RCLCPP_PUBLIC void add_callback_group (const rclcpp::CallbackGroup::SharedPtr &group_ptr, const rclcpp::node_interfaces::NodeBaseInterface::SharedPtr &node_ptr, bool notify=true) override
 Add a callback group to an 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...
 
RCLCPP_PUBLIC void remove_callback_group (const rclcpp::CallbackGroup::SharedPtr &group_ptr, bool notify=true) override
 Remove a callback group from the executor. More...
 
RCLCPP_PUBLIC void add_node (const rclcpp::node_interfaces::NodeBaseInterface::SharedPtr &node_ptr, bool notify=true) override
 Add a node to the executor. More...
 
RCLCPP_PUBLIC void add_node (const 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 (const rclcpp::node_interfaces::NodeBaseInterface::SharedPtr &node_ptr, bool notify=true) override
 Remove a node from the executor. More...
 
RCLCPP_PUBLIC void remove_node (const std::shared_ptr< rclcpp::Node > &node_ptr, bool notify=true) override
 Convenience function which takes Node and forwards NodeBaseInterface. More...
 
void add_callback_group_only (const rclcpp::CallbackGroup::SharedPtr &group_ptr)
 
RCLCPP_PUBLIC void spin () override
 
RCLCPP_PUBLIC void spin (const std::function< void(const std::exception &)> &exception_handler)
 
RCLCPP_PUBLIC void spin_once (std::chrono::nanoseconds timeout=std::chrono::nanoseconds(-1)) override
 Collect work once and execute the next available work, optionally within a duration. More...
 
RCLCPP_PUBLIC void spin_some (std::chrono::nanoseconds max_duration=std::chrono::nanoseconds(0)) override
 Collect work once and execute all available work, optionally within a max duration. More...
 
RCLCPP_PUBLIC bool collect_and_execute_ready_events (std::chrono::nanoseconds max_duration, bool recollect_if_no_work_available)
 
RCLCPP_PUBLIC void spin_all (std::chrono::nanoseconds max_duration) override
 Collect and execute work repeatedly within a duration or until no more work is available. More...
 
RCLCPP_PUBLIC void cancel () override
 Cancel any running spin* function, causing it to return. More...
 
RCLCPP_PUBLIC size_t get_number_of_threads () const
 
bool is_spinning ()
 
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))
 
- 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 (const 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 (const 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 (const 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 (const std::shared_ptr< rclcpp::Node > &node)
 Convenience function which takes Node and forwards NodeBaseInterface.
 
virtual RCLCPP_PUBLIC void spin_node_all (const 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 (const std::shared_ptr< rclcpp::Node > &node, std::chrono::nanoseconds max_duration)
 Convenience function which takes Node and forwards NodeBaseInterface.
 
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...
 
RCLCPP_PUBLIC bool is_spinning ()
 Returns true if the executor is currently spinning. More...
 

Protected Member Functions

RCLCPP_PUBLIC void run (size_t this_thread_number, bool block_initially)
 
RCLCPP_PUBLIC void run (size_t this_thread_number, const std::function< void(const std::exception &)> &exception_handler)
 
void shutdown ()
 
void set_callbacks (CallbackGroupData &cgd)
 
bool execute_previous_ready_executables_until (const std::chrono::time_point< std::chrono::steady_clock > &stop_time)
 
void unregister_event_callbacks (const rclcpp::CallbackGroup::SharedPtr &cbg) const
 
- 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 (const 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...
 
virtual RCLCPP_PUBLIC void handle_updated_entities (bool notify)
 This function triggers a recollect of all entities that are registered to the executor. More...
 
virtual RCLCPP_PUBLIC void spin_once_impl (std::chrono::nanoseconds timeout)
 
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.
 

Protected Attributes

std::unique_ptr< cbg_executor::CBGSchedulerscheduler
 
- 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::GuardConditioninterrupt_guard_condition_
 Guard condition for signaling the rmw layer to wake up for special events.
 
std::shared_ptr< rclcpp::GuardConditionshutdown_guard_condition_
 Guard condition for signaling the rmw layer to wake up for system shutdown.
 
std::mutex mutex_
 
std::shared_ptr< rclcpp::Contextcontext_
 The context associated with this executor.
 
std::shared_ptr< rclcpp::executors::ExecutorNotifyWaitablenotify_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< ExecutorImplementationimpl_
 Pointer to implementation.
 

Additional Inherited Members

- Static Protected Member Functions inherited from rclcpp::Executor
static RCLCPP_PUBLIC void execute_subscription (const rclcpp::SubscriptionBase::SharedPtr &subscription)
 Run subscription executable. More...
 
static RCLCPP_PUBLIC void execute_timer (const rclcpp::TimerBase::SharedPtr &timer, const std::shared_ptr< void > &data_ptr)
 Run timer executable. More...
 
static RCLCPP_PUBLIC void execute_service (const rclcpp::ServiceBase::SharedPtr &service)
 Run service server executable. More...
 
static RCLCPP_PUBLIC void execute_client (const rclcpp::ClientBase::SharedPtr &client)
 Run service client executable. More...
 

Detailed Description

Definition at line 40 of file events_cbg_executor.hpp.

Constructor & Destructor Documentation

◆ EventsCBGExecutor()

rclcpp::executors::EventsCBGExecutor::EventsCBGExecutor ( const rclcpp::ExecutorOptions options = rclcpp::ExecutorOptions(),
size_t  number_of_threads = 0,
std::chrono::nanoseconds  timeout = std::chrono::nanoseconds(-1) 
)
explicit

For the yield_before_execute option, when true std::this_thread::yield() will be called after acquiring work (as an AnyExecutable) and releasing the spinning lock, but before executing the work. This is useful for reproducing some bugs related to taking work more than once.

Parameters
optionscommon options for all executors
number_of_threadsnumber of threads to have in the thread pool, the default 0 will use the number of cpu cores found (minimum of 2)
timeoutmaximum time to wait

Definition at line 79 of file events_cbg_executor.cpp.

Member Function Documentation

◆ add_callback_group()

void rclcpp::executors::EventsCBGExecutor::add_callback_group ( const rclcpp::CallbackGroup::SharedPtr &  group_ptr,
const rclcpp::node_interfaces::NodeBaseInterface::SharedPtr &  node_ptr,
bool  notify = true 
)
overridevirtual

Add a callback group to an executor.

An executor can have zero or more callback groups which provide work during spin functions. When an executor attempts to add a callback group, the executor checks to see if it is already associated with another executor, and if it has been, then an exception is thrown. Otherwise, the callback group is added to the executor.

Adding a callback group with this method does not associate its node with this executor in any way

Parameters
[in]group_ptra shared ptr that points to a callback group
[in]node_ptra shared pointer that points to a node base interface
[in]notifyTrue to trigger the interrupt guard condition during this function. If the executor is blocked at the rmw layer while waiting for work and it is notified that a new callback group was added, it will wake up.
Exceptions
std::runtime_errorif the callback group is associated to an executor

Reimplemented from rclcpp::Executor.

Definition at line 534 of file events_cbg_executor.cpp.

◆ add_node() [1/2]

void rclcpp::executors::EventsCBGExecutor::add_node ( const rclcpp::node_interfaces::NodeBaseInterface::SharedPtr &  node_ptr,
bool  notify = true 
)
overridevirtual

Add a node to the executor.

Nodes have associated callback groups, and this method adds any of those callback groups to this executor which have their automatically_add_to_executor_with_node parameter true. The node is also associated with the executor so that future callback groups which are created on the node with the automatically_add_to_executor_with_node parameter set to true are also automatically associated with this executor.

Callback groups with the automatically_add_to_executor_with_node parameter set to false must be manually added to an executor using the rclcpp::Executor::add_callback_group method.

If a node is already associated with an executor, this method throws an exception.

Parameters
[in]node_ptrShared pointer to the node to be added.
[in]notifyTrue to trigger the interrupt guard condition during this function. If the executor is blocked at the rmw layer while waiting for work and it is notified that a new node was added, it will wake up.
Exceptions
std::runtime_errorif a node is already associated to an executor

Reimplemented from rclcpp::Executor.

Definition at line 716 of file events_cbg_executor.cpp.

◆ add_node() [2/2]

void rclcpp::executors::EventsCBGExecutor::add_node ( const std::shared_ptr< rclcpp::Node > &  node_ptr,
bool  notify = true 
)
overridevirtual

Convenience function which takes Node and forwards NodeBaseInterface.

See also
rclcpp::Executor::add_node

Reimplemented from rclcpp::Executor.

Definition at line 737 of file events_cbg_executor.cpp.

◆ cancel()

void rclcpp::executors::EventsCBGExecutor::cancel ( )
overridevirtual

Cancel any running spin* function, causing it to return.

This function can be called asynchonously from any thread.

Exceptions
std::runtime_errorif there is an issue triggering the guard condition

Reimplemented from rclcpp::Executor.

Definition at line 563 of file events_cbg_executor.cpp.

◆ collect_and_execute_ready_events()

bool rclcpp::executors::EventsCBGExecutor::collect_and_execute_ready_events ( std::chrono::nanoseconds  max_duration,
bool  recollect_if_no_work_available 
)
Returns
true if work was available and executed

Definition at line 454 of file events_cbg_executor.cpp.

References execute_previous_ready_executables_until(), and rclcpp::ok().

Referenced by spin_all(), and spin_some().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ execute_previous_ready_executables_until()

bool rclcpp::executors::EventsCBGExecutor::execute_previous_ready_executables_until ( const std::chrono::time_point< std::chrono::steady_clock > &  stop_time)
protected

This function will execute all available executables, that were ready, before this function was called.

Definition at line 191 of file events_cbg_executor.cpp.

Referenced by collect_and_execute_ready_events().

Here is the caller graph for this function:

◆ get_all_callback_groups()

std::vector< rclcpp::CallbackGroup::WeakPtr > rclcpp::executors::EventsCBGExecutor::get_all_callback_groups ( )
overridevirtual

Get callback groups that belong to executor.

This function returns a vector of weak pointers that point to callback groups that were associated with the executor. The callback groups associated with this executor may have been added with add_callback_group, or added when a node was added to the executor with add_node, or automatically added when it created by a node already associated with this executor and the automatically_add_to_executor_with_node parameter was true.

Returns
a vector of weak pointers that point to callback groups that are associated with the executor

Reimplemented from rclcpp::Executor.

Definition at line 582 of file events_cbg_executor.cpp.

◆ get_automatically_added_callback_groups_from_nodes()

std::vector< rclcpp::CallbackGroup::WeakPtr > rclcpp::executors::EventsCBGExecutor::get_automatically_added_callback_groups_from_nodes ( )
overridevirtual

Get callback groups that belong to executor.

This function returns a vector of weak pointers that point to callback groups that were added from a node that is associated with the executor. The callback groups are added when a node is added to the executor with add_node, or automatically if they are created in the future by that node and have the automatically_add_to_executor_with_node argument set to true.

Returns
a vector of weak pointers that point to callback groups from a node associated with the executor

Reimplemented from rclcpp::Executor.

Definition at line 614 of file events_cbg_executor.cpp.

◆ get_manually_added_callback_groups()

std::vector< rclcpp::CallbackGroup::WeakPtr > rclcpp::executors::EventsCBGExecutor::get_manually_added_callback_groups ( )
overridevirtual

Get callback groups that belong to executor.

This function returns a vector of weak pointers that point to callback groups that were associated with the executor. The callback groups associated with this executor have been added with add_callback_group.

Returns
a vector of weak pointers that point to callback groups that are associated with the executor

Reimplemented from rclcpp::Executor.

Definition at line 597 of file events_cbg_executor.cpp.

◆ remove_callback_group()

void rclcpp::executors::EventsCBGExecutor::remove_callback_group ( const rclcpp::CallbackGroup::SharedPtr &  group_ptr,
bool  notify = true 
)
overridevirtual

Remove a callback group from the executor.

The callback group is removed from and disassociated with the executor. If the callback group removed was the last callback group from the node that is associated with the executor, the interrupt guard condition is triggered and node's guard condition is removed from the executor.

This function only removes a callback group that was manually added with rclcpp::Executor::add_callback_group. To remove callback groups that were added from a node using rclcpp::Executor::add_node, use rclcpp::Executor::remove_node instead.

Parameters
[in]group_ptrShared pointer to the callback group to be added.
[in]notifyTrue to trigger the interrupt guard condition during this function. If the executor is blocked at the rmw layer while waiting for work and it is notified that a callback group was removed, it will wake up.
Exceptions
std::runtime_errorif node is deleted before callback group
std::runtime_errorif the callback group is not associated with the executor

Reimplemented from rclcpp::Executor.

Definition at line 663 of file events_cbg_executor.cpp.

◆ remove_node() [1/2]

void rclcpp::executors::EventsCBGExecutor::remove_node ( const rclcpp::node_interfaces::NodeBaseInterface::SharedPtr &  node_ptr,
bool  notify = true 
)
overridevirtual

Remove a node from the executor.

Any callback groups automatically added when this node was added with rclcpp::Executor::add_node are automatically removed, and the node is no longer associated with this executor.

This also means that future callback groups created by the given node are no longer automatically added to this executor.

Parameters
[in]node_ptrShared pointer to the node to remove.
[in]notifyTrue to trigger the interrupt guard condition and wake up the executor. This is useful if the last node was removed from the executor while the executor was blocked waiting for work in another thread, because otherwise the executor would never be notified.
Exceptions
std::runtime_errorif the node is not associated with an executor.
std::runtime_errorif the node is not associated with this executor.

Reimplemented from rclcpp::Executor.

Definition at line 743 of file events_cbg_executor.cpp.

◆ remove_node() [2/2]

void rclcpp::executors::EventsCBGExecutor::remove_node ( const 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 792 of file events_cbg_executor.cpp.

◆ shutdown()

void rclcpp::executors::EventsCBGExecutor::shutdown ( )
protected

Te be called in termination case. E.g. destructor of shutdown callback. Stops the scheduler and cleans up the internal data structures.

Definition at line 122 of file events_cbg_executor.cpp.

◆ spin() [1/2]

void rclcpp::executors::EventsCBGExecutor::spin ( )
overridevirtual
See also
rclcpp::Executor:spin() for more details
Exceptions
std::runtime_errorwhen spin() called while already spinning

Implements rclcpp::Executor.

Definition at line 489 of file events_cbg_executor.cpp.

◆ spin() [2/2]

RCLCPP_PUBLIC void rclcpp::executors::EventsCBGExecutor::spin ( const std::function< void(const std::exception &)> &  exception_handler)
See also
rclcpp::Executor:spin() for more details
Exceptions
std::runtime_errorwhen spin() called while already spinning
Parameters
exception_handlerwill be called for every exception in the processing threads

The exception_handler can be called from multiple threads at the same time. The exception_handler shall rethrow the exception it if wants to terminate the program.

◆ spin_all()

void rclcpp::executors::EventsCBGExecutor::spin_all ( std::chrono::nanoseconds  max_duration)
overridevirtual

Collect and execute work repeatedly within a duration or until no more work is available.

This function can be overridden. The default implementation is suitable for a single-threaded model of execution. Adding subscriptions, timers, services, etc. with blocking callbacks will cause this function to block (which may have unintended consequences). If the time that waitables take to be executed is longer than the period on which new waitables become ready, this method will execute work repeatedly until max_duration has elapsed.

Parameters
[in]max_durationThe maximum amount of time to spend executing work, must be >= 0. 0 is potentially block forever until no more work is available.
Exceptions
std::invalid_argumentif max_duration is less than 0. Note that spin_all() may take longer than this time as it only returns once max_duration has been exceeded.

Reimplemented from rclcpp::Executor.

Definition at line 445 of file events_cbg_executor.cpp.

References collect_and_execute_ready_events().

Here is the call graph for this function:

◆ spin_once()

void rclcpp::executors::EventsCBGExecutor::spin_once ( std::chrono::nanoseconds  timeout = std::chrono::nanoseconds(-1))
overridevirtual

Collect work once and execute the next available work, optionally within a duration.

This function can be overridden. The default implementation is suitable for a single-thread model of execution. Adding subscriptions, timers, services, etc. with blocking callbacks will cause this function to block (which may have unintended consequences).

Parameters
[in]timeoutThe maximum amount of time to spend waiting for work. -1 is potentially block forever waiting for work.

Reimplemented from rclcpp::Executor.

Definition at line 428 of file events_cbg_executor.cpp.

◆ spin_some()

void rclcpp::executors::EventsCBGExecutor::spin_some ( std::chrono::nanoseconds  max_duration = std::chrono::nanoseconds(0))
overridevirtual

Collect work once and execute all available work, optionally within a max duration.

This function can be overridden. The default implementation is suitable for a single-threaded model of execution. Adding subscriptions, timers, services, etc. with blocking or long running callbacks may cause the function exceed the max_duration significantly.

Work that is ready to be done is collected only once, and when collecting that work entities which may have multiple pieces of work ready will only be executed at most one time. The reason for this is that it is not possible to tell if, for example, a ready subscription has only one message ready or multiple without checking again. Because, in order to find out if there are multiple messages, one message must be taken and executed before checking again if that subscription is still ready. However, this function only checks for ready entities to work on once, and so it will never execute a single entity more than once per call to this function. See spin_all() variants for a function that will repeatedly work on a single entity in a single call.

If there is no work to be done when this called, it will return immediately because the collecting of available work is non-blocking. Before each piece of ready work is executed this function checks if the max_duration has been exceeded, and if it has it returns without starting the execution of the next piece of work.

If a max_duration of 0 is given, then all of the collected work will be executed before the function returns.

Parameters
[in]max_durationThe maximum amount of time to spend executing work, or 0 for no limit.

Reimplemented from rclcpp::Executor.

Definition at line 440 of file events_cbg_executor.cpp.

References collect_and_execute_ready_events().

Here is the call graph for this function:

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