Execution and Callbacks¶
There are two components that control the execution of callbacks: executors and callback groups.
Executors are responsible for the actual execution of callbacks and should extend the Executor
class.
Callback groups are used to enforce concurrency rules for callbacks and should extend the CallbackGroup
class.
Executors¶
-
class
rclpy.executors.
Executor
(*, context=None)¶ A base class for an executor.
An executor controls the threading model used to process callbacks. Callbacks are units of work like subscription callbacks, timer callbacks, service calls, and received client responses. An executor controls which threads callbacks get executed in.
A custom executor must define
Executor.spin_once()
. If the executor has any cleanup then it should also defineExecutor.shutdown()
.Parameters: context – The context to be associated with, or None for the default global context. -
add_node
(node)¶ Add a node whose callbacks should be managed by this executor.
Return true if the node was added.
Return type: bool
-
can_execute
(entity)¶ Determine if a callback for an entity can be executed.
Parameters: entity – Subscription, Timer, Guard condition, etc Returns: True if the entity callback can be executed Return type: bool
-
context
¶
-
create_task
(callback, *args, **kwargs)¶ Add a callback or coroutine to be executed during
spin()
and return a Future.Arguments to this function are passed to the callback.
Parameters: callback (callable or coroutine function) – A callback to be run in the executor Return type: rclpy.task.Future
instance
-
get_nodes
()¶ Return nodes which have been added to this executor.
Return type: list
-
remove_node
(node)¶ Stop managing this node’s callbacks.
-
shutdown
(timeout_sec=None)¶ Stop executing callbacks and wait for their completion.
Return true if all outstanding callbacks finished executing.
Parameters: timeout_sec (float or None) – Seconds to wait. Block forever if None or negative. Don’t wait if 0 Return type: bool
-
spin
()¶ Execute callbacks until shutdown.
-
spin_once
(timeout_sec=None)¶ Wait for and execute a single callback.
A custom executor should use
Executor.wait_for_ready_callbacks()
to get work.Parameters: timeout_sec (float or None) – Seconds to wait. Block forever if None or negative. Don’t wait if 0 Return type: None
-
spin_until_future_complete
(future)¶ Execute until a given future is done.
-
wait_for_ready_callbacks
(*args, **kwargs)¶ Reuse generator and return callbacks that are ready to be performed.
See
Executor._wait_for_ready_callbacks()
for documentation
-
-
class
rclpy.executors.
MultiThreadedExecutor
(num_threads=None, *, context=None)¶ Runs callbacks in a pool of threads.
Initialize the executor.
Parameters: num_threads (int) – number of worker threads in the pool. If None the number of threads will use multiprocessing.cpu_count(). If that’s not implemented the number of threads defaults to 1. -
spin_once
(timeout_sec=None)¶ Wait for and execute a single callback.
A custom executor should use
Executor.wait_for_ready_callbacks()
to get work.Parameters: timeout_sec (float or None) – Seconds to wait. Block forever if None or negative. Don’t wait if 0 Return type: None
-
-
class
rclpy.executors.
SingleThreadedExecutor
(*, context=None)¶ Runs callbacks in the thread which calls
SingleThreadedExecutor.spin()
.-
spin_once
(timeout_sec=None)¶ Wait for and execute a single callback.
A custom executor should use
Executor.wait_for_ready_callbacks()
to get work.Parameters: timeout_sec (float or None) – Seconds to wait. Block forever if None or negative. Don’t wait if 0 Return type: None
-
-
exception
rclpy.executors.
TimeoutException
¶ Signal that a timeout occurred.
-
rclpy.executors.
await_or_execute
(callback, *args)¶ Await a callback if it is a coroutine, else execute it.
Callback Groups¶
-
class
rclpy.callback_groups.
CallbackGroup
¶ Control when callbacks are allowed to be executed.
-
add_entity
(entity)¶ Add an entity to the callback group.
Parameters: entity – a subscription, timer, client, or service instance Return type: None
-
beginning_execution
(entity)¶ Get permission from the callback from the group to begin executing an entity.
Return true if the callback can be executed, false otherwise. If this returns True then
CallbackGroup.ending_execution()
must be called after the callback has been executed.Parameters: entity – a subscription, timer, client, or service instance Return type: bool
-
can_execute
(entity)¶ Return true if an entity can be executed.
Parameters: entity – a subscription, timer, client, or service instance Return type: bool
-
ending_execution
(entity)¶ Notify group that a callback has finished executing.
Parameters: entity – a subscription, timer, client, or service instance Return type: None
-
has_entity
(entity)¶ Determine if an entity has been added to this group.
Parameters: entity – a subscription, timer, client, or service instance Return type: bool
-
-
class
rclpy.callback_groups.
MutuallyExclusiveCallbackGroup
¶ Allow only one callback to be executing at a time.
-
beginning_execution
(entity)¶ Get permission from the callback from the group to begin executing an entity.
Return true if the callback can be executed, false otherwise. If this returns True then
CallbackGroup.ending_execution()
must be called after the callback has been executed.Parameters: entity – a subscription, timer, client, or service instance Return type: bool
-
can_execute
(entity)¶ Return true if an entity can be executed.
Parameters: entity – a subscription, timer, client, or service instance Return type: bool
-
ending_execution
(entity)¶ Notify group that a callback has finished executing.
Parameters: entity – a subscription, timer, client, or service instance Return type: None
-
-
class
rclpy.callback_groups.
ReentrantCallbackGroup
¶ Allow callbacks to be executed in parallel without restriction.
-
beginning_execution
(entity)¶ Get permission from the callback from the group to begin executing an entity.
Return true if the callback can be executed, false otherwise. If this returns True then
CallbackGroup.ending_execution()
must be called after the callback has been executed.Parameters: entity – a subscription, timer, client, or service instance Return type: bool
-
can_execute
(entity)¶ Return true if an entity can be executed.
Parameters: entity – a subscription, timer, client, or service instance Return type: bool
-
ending_execution
(entity)¶ Notify group that a callback has finished executing.
Parameters: entity – a subscription, timer, client, or service instance Return type: None
-