rclcpp  master
C++ ROS Client Library API
Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes | List of all members
rclcpp::Executor Class Referenceabstract

Coordinate the order and timing of available communication tasks. More...

#include <executor.hpp>

Inheritance diagram for rclcpp::Executor:
Inheritance graph
[legend]
Collaboration diagram for rclcpp::Executor:
Collaboration graph
[legend]

Public Member Functions

 Executor (const rclcpp::ExecutorOptions &options=rclcpp::ExecutorOptions())
 Default constructor. More...
 
virtual ~Executor ()
 Default destructor. More...
 
virtual void spin ()=0
 Do work periodically as it becomes available to us. Blocking call, may block indefinitely. More...
 
virtual void add_node (rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node_ptr, bool notify=true)
 Add a node to the executor. More...
 
virtual void add_node (std::shared_ptr< rclcpp::Node > node_ptr, bool notify=true)
 Convenience function which takes Node and forwards NodeBaseInterface. More...
 
virtual void remove_node (rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node_ptr, bool notify=true)
 Remove a node from the executor. More...
 
virtual void remove_node (std::shared_ptr< rclcpp::Node > node_ptr, bool notify=true)
 Convenience function which takes Node and forwards NodeBaseInterface. More...
 
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. More...
 
void spin_node_some (rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node)
 Add a node, complete all immediately available work, and remove the node. More...
 
void spin_node_some (std::shared_ptr< rclcpp::Node > node)
 Convenience function which takes Node and forwards NodeBaseInterface. More...
 
virtual void spin_some (std::chrono::nanoseconds max_duration=std::chrono::nanoseconds(0))
 Complete all available queued work without blocking. More...
 
virtual void spin_once (std::chrono::nanoseconds timeout=std::chrono::nanoseconds(-1))
 
template<typename ResponseT , typename TimeRepT = int64_t, typename TimeT = std::milli>
FutureReturnCode spin_until_future_complete (const std::shared_future< ResponseT > &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...
 
void cancel ()
 Cancel any running spin* function, causing it to return. More...
 
void set_memory_strategy (memory_strategy::MemoryStrategy::SharedPtr memory_strategy)
 Support dynamic switching of the memory strategy. More...
 

Protected Member Functions

void spin_node_once_nanoseconds (rclcpp::node_interfaces::NodeBaseInterface::SharedPtr node, std::chrono::nanoseconds timeout)
 
void execute_any_executable (AnyExecutable &any_exec)
 Find the next available executable and do the work associated with it. More...
 
void wait_for_work (std::chrono::nanoseconds timeout=std::chrono::nanoseconds(-1))
 
rclcpp::node_interfaces::NodeBaseInterface::SharedPtr get_node_by_group (rclcpp::CallbackGroup::SharedPtr group)
 
rclcpp::CallbackGroup::SharedPtr get_group_by_timer (rclcpp::TimerBase::SharedPtr timer)
 
bool get_next_ready_executable (AnyExecutable &any_executable)
 
bool get_next_executable (AnyExecutable &any_executable, std::chrono::nanoseconds timeout=std::chrono::nanoseconds(-1))
 

Static Protected Member Functions

static void execute_subscription (rclcpp::SubscriptionBase::SharedPtr subscription)
 
static void execute_timer (rclcpp::TimerBase::SharedPtr timer)
 
static void execute_service (rclcpp::ServiceBase::SharedPtr service)
 
static void execute_client (rclcpp::ClientBase::SharedPtr client)
 

Protected Attributes

std::atomic_bool spinning
 Spinning state, used to prevent multi threaded calls to spin and to cancel blocking spins. More...
 
rcl_guard_condition_t interrupt_guard_condition_ = rcl_get_zero_initialized_guard_condition()
 Guard condition for signaling the rmw layer to wake up for special events. More...
 
rcl_wait_set_t wait_set_ = rcl_get_zero_initialized_wait_set()
 Wait set for managing entities that the rmw layer waits on. More...
 
std::mutex memory_strategy_mutex_
 
memory_strategy::MemoryStrategy::SharedPtr memory_strategy_
 The memory strategy: an interface for handling user-defined memory allocation strategies. More...
 
std::shared_ptr< rclcpp::Contextcontext_
 The context associated with this executor. More...
 
std::list< rclcpp::node_interfaces::NodeBaseInterface::WeakPtr > weak_nodes_
 
std::list< const rcl_guard_condition_t * > guard_conditions_
 

Detailed Description

Coordinate the order and timing of available communication tasks.

Executor provides spin functions (including spin_node_once and spin_some). It coordinates the nodes and callback groups by looking for available work and completing it, based on the threading or concurrency scheme provided by the subclass implementation. An example of available work is executing a subscription callback, or a timer callback. The executor structure allows for a decoupling of the communication graph and the execution model. See SingleThreadedExecutor and MultiThreadedExecutor for examples of execution paradigms.

Constructor & Destructor Documentation

◆ Executor()

rclcpp::Executor::Executor ( const rclcpp::ExecutorOptions options = rclcpp::ExecutorOptions())
explicit

Default constructor.

Parameters
[in]optionsOptions used to configure the executor.

◆ ~Executor()

virtual rclcpp::Executor::~Executor ( )
virtual

Default destructor.

Member Function Documentation

◆ spin()

virtual void rclcpp::Executor::spin ( )
pure virtual

Do work periodically as it becomes available to us. Blocking call, may block indefinitely.

Implemented in rclcpp::executors::StaticSingleThreadedExecutor, rclcpp::executors::MultiThreadedExecutor, and rclcpp::executors::SingleThreadedExecutor.

◆ add_node() [1/2]

virtual void rclcpp::Executor::add_node ( rclcpp::node_interfaces::NodeBaseInterface::SharedPtr  node_ptr,
bool  notify = true 
)
virtual

Add a node to the executor.

An executor can have zero or more nodes which provide work during spin functions.

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.

Reimplemented in rclcpp::executors::StaticSingleThreadedExecutor.

◆ add_node() [2/2]

virtual void rclcpp::Executor::add_node ( std::shared_ptr< rclcpp::Node node_ptr,
bool  notify = true 
)
virtual

Convenience function which takes Node and forwards NodeBaseInterface.

See also
rclcpp::Executor::add_node

Reimplemented in rclcpp::executors::StaticSingleThreadedExecutor.

◆ remove_node() [1/2]

virtual void rclcpp::Executor::remove_node ( rclcpp::node_interfaces::NodeBaseInterface::SharedPtr  node_ptr,
bool  notify = true 
)
virtual

Remove a node from the 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.

Reimplemented in rclcpp::executors::StaticSingleThreadedExecutor.

◆ remove_node() [2/2]

virtual void rclcpp::Executor::remove_node ( std::shared_ptr< rclcpp::Node node_ptr,
bool  notify = true 
)
virtual

Convenience function which takes Node and forwards NodeBaseInterface.

See also
rclcpp::Executor::remove_node

Reimplemented in rclcpp::executors::StaticSingleThreadedExecutor.

◆ spin_node_once() [1/2]

template<typename RepT = int64_t, typename T = std::milli>
void rclcpp::Executor::spin_node_once ( rclcpp::node_interfaces::NodeBaseInterface::SharedPtr  node,
std::chrono::duration< RepT, T >  timeout = std::chrono::duration<RepT, T>(-1) 
)
inline

Add a node to executor, execute the next available unit of work, and remove the node.

Parameters
[in]nodeShared pointer to the node to add.
[in]timeoutHow long to wait for work to become available. Negative values cause spin_node_once to block indefinitely (the default behavior). A timeout of 0 causes this function to be non-blocking.

◆ spin_node_once() [2/2]

template<typename NodeT = rclcpp::Node, typename RepT = int64_t, typename T = std::milli>
void rclcpp::Executor::spin_node_once ( std::shared_ptr< NodeT >  node,
std::chrono::duration< RepT, T >  timeout = std::chrono::duration<RepT, T>(-1) 
)
inline

Convenience function which takes Node and forwards NodeBaseInterface.

◆ spin_node_some() [1/2]

void rclcpp::Executor::spin_node_some ( rclcpp::node_interfaces::NodeBaseInterface::SharedPtr  node)

Add a node, complete all immediately available work, and remove the node.

Parameters
[in]nodeShared pointer to the node to add.

◆ spin_node_some() [2/2]

void rclcpp::Executor::spin_node_some ( std::shared_ptr< rclcpp::Node node)

Convenience function which takes Node and forwards NodeBaseInterface.

◆ spin_some()

virtual void rclcpp::Executor::spin_some ( std::chrono::nanoseconds  max_duration = std::chrono::nanoseconds(0))
virtual

Complete all available queued work without blocking.

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).

Parameters
[in]max_durationThe maximum amount of time to spend executing work, or 0 for no limit. Note that spin_some() may take longer than this time as it only returns once max_duration has been exceeded.

◆ spin_once()

virtual void rclcpp::Executor::spin_once ( std::chrono::nanoseconds  timeout = std::chrono::nanoseconds(-1))
virtual

◆ spin_until_future_complete()

template<typename ResponseT , typename TimeRepT = int64_t, typename TimeT = std::milli>
FutureReturnCode rclcpp::Executor::spin_until_future_complete ( const std::shared_future< ResponseT > &  future,
std::chrono::duration< TimeRepT, TimeT >  timeout = std::chrono::duration<TimeRepT, TimeT>(-1) 
)
inline

Spin (blocking) until the future is complete, it times out waiting, or rclcpp is interrupted.

Parameters
[in]futureThe future to wait on. If this function returns SUCCESS, the future can be accessed without blocking (though it may still throw an exception).
[in]timeoutOptional timeout parameter, which gets passed to Executor::spin_node_once. -1 is block forever, 0 is non-blocking. If the time spent inside the blocking loop exceeds this timeout, return a TIMEOUT return code.
Returns
The return code, one of SUCCESS, INTERRUPTED, or TIMEOUT.

◆ cancel()

void rclcpp::Executor::cancel ( )

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

◆ set_memory_strategy()

void rclcpp::Executor::set_memory_strategy ( memory_strategy::MemoryStrategy::SharedPtr  memory_strategy)

Support dynamic switching of the memory strategy.

Switching the memory strategy while the executor is spinning in another threading could have unintended consequences.

Parameters
[in]memory_strategyShared pointer to the memory strategy to set.
Exceptions
std::runtime_errorif memory_strategy is null

◆ spin_node_once_nanoseconds()

void rclcpp::Executor::spin_node_once_nanoseconds ( rclcpp::node_interfaces::NodeBaseInterface::SharedPtr  node,
std::chrono::nanoseconds  timeout 
)
protected

◆ execute_any_executable()

void rclcpp::Executor::execute_any_executable ( AnyExecutable any_exec)
protected

Find the next available executable and do the work associated with it.

Parameters
[in]any_execUnion structure that can hold any executable type (timer, subscription, service, client).
Exceptions
std::runtime_errorif there is an issue triggering the guard condition

◆ execute_subscription()

static void rclcpp::Executor::execute_subscription ( rclcpp::SubscriptionBase::SharedPtr  subscription)
staticprotected

◆ execute_timer()

static void rclcpp::Executor::execute_timer ( rclcpp::TimerBase::SharedPtr  timer)
staticprotected

◆ execute_service()

static void rclcpp::Executor::execute_service ( rclcpp::ServiceBase::SharedPtr  service)
staticprotected

◆ execute_client()

static void rclcpp::Executor::execute_client ( rclcpp::ClientBase::SharedPtr  client)
staticprotected

◆ wait_for_work()

void rclcpp::Executor::wait_for_work ( std::chrono::nanoseconds  timeout = std::chrono::nanoseconds(-1))
protected
Exceptions
std::runtime_errorif the wait set can be cleared

◆ get_node_by_group()

rclcpp::node_interfaces::NodeBaseInterface::SharedPtr rclcpp::Executor::get_node_by_group ( rclcpp::CallbackGroup::SharedPtr  group)
protected

◆ get_group_by_timer()

rclcpp::CallbackGroup::SharedPtr rclcpp::Executor::get_group_by_timer ( rclcpp::TimerBase::SharedPtr  timer)
protected

◆ get_next_ready_executable()

bool rclcpp::Executor::get_next_ready_executable ( AnyExecutable any_executable)
protected

◆ get_next_executable()

bool rclcpp::Executor::get_next_executable ( AnyExecutable any_executable,
std::chrono::nanoseconds  timeout = std::chrono::nanoseconds(-1) 
)
protected

Member Data Documentation

◆ spinning

std::atomic_bool rclcpp::Executor::spinning
protected

Spinning state, used to prevent multi threaded calls to spin and to cancel blocking spins.

◆ interrupt_guard_condition_

rcl_guard_condition_t rclcpp::Executor::interrupt_guard_condition_ = rcl_get_zero_initialized_guard_condition()
protected

Guard condition for signaling the rmw layer to wake up for special events.

◆ wait_set_

rcl_wait_set_t rclcpp::Executor::wait_set_ = rcl_get_zero_initialized_wait_set()
protected

Wait set for managing entities that the rmw layer waits on.

◆ memory_strategy_mutex_

std::mutex rclcpp::Executor::memory_strategy_mutex_
protected

◆ memory_strategy_

memory_strategy::MemoryStrategy::SharedPtr rclcpp::Executor::memory_strategy_
protected

The memory strategy: an interface for handling user-defined memory allocation strategies.

◆ context_

std::shared_ptr<rclcpp::Context> rclcpp::Executor::context_
protected

The context associated with this executor.

◆ weak_nodes_

std::list<rclcpp::node_interfaces::NodeBaseInterface::WeakPtr> rclcpp::Executor::weak_nodes_
protected

◆ guard_conditions_

std::list<const rcl_guard_condition_t *> rclcpp::Executor::guard_conditions_
protected

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