Class EventsCBGExecutor
Defined in File events_cbg_executor.hpp
Nested Relationships
Nested Types
Inheritance Relationships
Base Type
public rclcpp::Executor(Class Executor)
Class Documentation
-
class EventsCBGExecutor : public rclcpp::Executor
Public Functions
-
explicit EventsCBGExecutor(const rclcpp::ExecutorOptions &options = rclcpp::ExecutorOptions(), size_t number_of_threads = 0, std::chrono::nanoseconds timeout = std::chrono::nanoseconds(-1))
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:
options – common options for all executors
number_of_threads – number of threads to have in the thread pool, the default 0 will use the number of cpu cores found (minimum of 2)
timeout – maximum time to wait
-
virtual ~EventsCBGExecutor()
Add a callback group to an executor.
An executor can have zero or more callback groups which provide work during
spinfunctions. 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:
group_ptr – [in] a shared ptr that points to a callback group
node_ptr – [in] a shared pointer that points to a node base interface
notify – [in] True 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.
- Throws:
std::runtime_error – if the callback group is associated to an executor
-
virtual std::vector<rclcpp::CallbackGroup::WeakPtr> get_all_callback_groups() override
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 withadd_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
-
virtual std::vector<rclcpp::CallbackGroup::WeakPtr> get_manually_added_callback_groups() override
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
-
virtual std::vector<rclcpp::CallbackGroup::WeakPtr> get_automatically_added_callback_groups_from_nodes() override
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
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:
group_ptr – [in] Shared pointer to the callback group to be added.
notify – [in] True 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.
- Throws:
std::runtime_error – if node is deleted before callback group
std::runtime_error – if the callback group is not associated with the executor
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:
node_ptr – [in] Shared pointer to the node to be added.
notify – [in] True 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.
- Throws:
std::runtime_error – if a node is already associated to an executor
Convenience function which takes Node and forwards NodeBaseInterface.
See also
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:
node_ptr – [in] Shared pointer to the node to remove.
notify – [in] True 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.
- Throws:
std::runtime_error – if the node is not associated with an executor.
std::runtime_error – if the node is not associated with this executor.
Convenience function which takes Node and forwards NodeBaseInterface.
See also
-
virtual void spin() override
See also
rclcpp::Executor:spin() for more details
- Throws:
std::runtime_error – when spin() called while already spinning
-
void spin(const std::function<void(const std::exception&)> &exception_handler)
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.
See also
rclcpp::Executor:spin() for more details
- Throws:
std::runtime_error – when spin() called while already spinning
- Parameters:
exception_handler – will be called for every exception in the processing threads
-
virtual 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.
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:
timeout – [in] The maximum amount of time to spend waiting for work.
-1is potentially block forever waiting for work.
-
virtual 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.
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:
max_duration – [in] The maximum amount of time to spend executing work, or 0 for no limit.
-
bool collect_and_execute_ready_events(std::chrono::nanoseconds max_duration, bool recollect_if_no_work_available)
- Returns:
true if work was available and executed
-
virtual void spin_all(std::chrono::nanoseconds max_duration) override
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_durationhas elapsed.- Parameters:
max_duration – [in] The maximum amount of time to spend executing work, must be >= 0.
0is potentially block forever until no more work is available.- Throws:
std::invalid_argument – if 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.
-
virtual void cancel() override
Cancel any running spin* function, causing it to return.
This function can be called asynchonously from any thread.
- Throws:
std::runtime_error – if there is an issue triggering the guard condition
-
size_t get_number_of_threads() const
-
inline bool is_spinning()
Protected Functions
-
void run(size_t this_thread_number, bool block_initially)
-
void run(size_t this_thread_number, const std::function<void(const std::exception&)> &exception_handler)
-
void shutdown()
Te be called in termination case. E.g. destructor of shutdown callback. Stops the scheduler and cleans up the internal data structures.
-
void set_callbacks(CallbackGroupData &cgd)
-
bool execute_previous_ready_executables_until(const std::chrono::time_point<std::chrono::steady_clock> &stop_time)
This function will execute all available executables, that were ready, before this function was called.
Protected Attributes
-
std::unique_ptr<cbg_executor::CBGScheduler> scheduler
-
explicit EventsCBGExecutor(const rclcpp::ExecutorOptions &options = rclcpp::ExecutorOptions(), size_t number_of_threads = 0, std::chrono::nanoseconds timeout = std::chrono::nanoseconds(-1))