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¶
- exception rclpy.executors.ConditionReachedException¶
Future has been completed.
- class rclpy.executors.Executor(*, context=None)¶
The 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
spin_once()
. If the executor has any cleanup then it should also defineshutdown()
.- Parameters
context (
Optional
[Context
]) – The context to be associated with, orNone
for the default global context.
- add_node(node)¶
Add a node whose callbacks should be managed by this executor.
- Parameters
node (Node) – The node to add to the executor.
- Return type
bool
- Returns
True
if the node was added,False
otherwise.
- can_execute(entity)¶
Determine if a callback for an entity can be executed.
- Parameters
entity (~WaitableEntityType) – Subscription, Timer, Guard condition, etc
- Return type
bool
- Returns
True
if the entity callback can be executed,False
otherwise.
- property context: rclpy.context.Context¶
Get the context associated with the executor.
- Return type
- 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 (
Union
[Callable
,Coroutine
]) – A callback to be run in the executor.- Return type
Task
- get_nodes()¶
Return nodes that have been added to this executor.
- Return type
List
[ForwardRef
]
- remove_node(node)¶
Stop managing this node’s callbacks.
- Parameters
node (Node) – The node to remove from the executor.
- Return type
None
- shutdown(timeout_sec=None)¶
Stop executing callbacks and wait for their completion.
- Parameters
timeout_sec (
Optional
[float
]) – Seconds to wait. Block forever ifNone
or negative. Don’t wait if 0.- Return type
bool
- Returns
True
if all outstanding callbacks finished executing, orFalse
if the timeot expires before all outstanding work is done.
- spin()¶
Execute callbacks until shutdown.
- Return type
None
- spin_once(timeout_sec=None)¶
Wait for and execute a single callback.
A custom executor should use
wait_for_ready_callbacks()
to get work.- Parameters
timeout_sec (
Optional
[float
]) – Seconds to wait. Block forever ifNone
or negative. Don’t wait if 0.- Return type
None
- spin_once_until_future_complete(future, timeout_sec=None)¶
Wait for and execute a single callback.
This should behave in the same way as
spin_once()
. If needed by the implementation, it should awake other threads waiting.- Parameters
future (
Future
) – The executor will wait until this future is done.timeout_sec (
Optional
[float
]) – Maximum seconds to wait. Block forever ifNone
or negative. Don’t wait if 0.
- Return type
None
- spin_until_future_complete(future, timeout_sec=None)¶
Execute callbacks until a given future is done or a timeout occurs.
- Return type
None
- wait_for_ready_callbacks(*args, **kwargs)¶
Return callbacks that are ready to be executed.
The arguments to this function are passed to the internal method
_wait_for_ready_callbacks()
to get a generator for ready callbacks:- _wait_for_ready_callbacks(timeout_sec=None, nodes=None, condition=<function Executor.<lambda>>)¶
Yield callbacks that are ready to be executed.
- Raises
TimeoutException – on timeout.
ShutdownException – on if executor was shut down.
- Parameters
timeout_sec (
float
) – Seconds to wait. Block forever ifNone
or negative. Don’t wait if 0.nodes (
List
[ForwardRef
]) – A list of nodes to wait on. Wait on all nodes ifNone
.condition (
Callable
[[],bool
]) – A callable that makes the function return immediately when it evaluates to True.
- Return type
Generator
[Tuple
[Task
, ~WaitableEntityType,ForwardRef
],None
,None
]
- Return type
Tuple
[Task
, ~WaitableEntityType,ForwardRef
]
- wake()¶
Wake the executor because something changed.
This is used to tell the executor when entities are created or destroyed.
- Return type
None
- exception rclpy.executors.ExternalShutdownException¶
Context has been shutdown.
- class rclpy.executors.MultiThreadedExecutor(num_threads=None, *, context=None)¶
Runs callbacks in a pool of threads.
- Parameters
num_threads (
Optional
[int
]) – number of worker threads in the pool. IfNone
, the number of threads will usemultiprocessing.cpu_count()
. If that’s not implemented the number of threads defaults to 1.context (
Optional
[Context
]) – The context associated with the executor.
- spin_once(timeout_sec=None)¶
Wait for and execute a single callback.
A custom executor should use
wait_for_ready_callbacks()
to get work.- Parameters
timeout_sec (
Optional
[float
]) – Seconds to wait. Block forever ifNone
or negative. Don’t wait if 0.- Return type
None
- spin_once_until_future_complete(future, timeout_sec=None)¶
Wait for and execute a single callback.
This should behave in the same way as
spin_once()
. If needed by the implementation, it should awake other threads waiting.- Parameters
future (
Future
) – The executor will wait until this future is done.timeout_sec (
Optional
[float
]) – Maximum seconds to wait. Block forever ifNone
or negative. Don’t wait if 0.
- Return type
None
- exception rclpy.executors.ShutdownException¶
Signal that executor was shut down.
- class rclpy.executors.SingleThreadedExecutor(*, context=None)¶
Runs callbacks in the thread that calls
Executor.spin()
.- spin_once(timeout_sec=None)¶
Wait for and execute a single callback.
A custom executor should use
wait_for_ready_callbacks()
to get work.- Parameters
timeout_sec (
Optional
[float
]) – Seconds to wait. Block forever ifNone
or negative. Don’t wait if 0.- Return type
None
- spin_once_until_future_complete(future, timeout_sec=None)¶
Wait for and execute a single callback.
This should behave in the same way as
spin_once()
. If needed by the implementation, it should awake other threads waiting.- Parameters
future (
Future
) – The executor will wait until this future is done.timeout_sec (
Optional
[float
]) – Maximum seconds to wait. Block forever ifNone
or negative. Don’t wait if 0.
- Return type
None
- exception rclpy.executors.TimeoutException¶
Signal that a timeout occurred.
- async rclpy.executors.await_or_execute(callback, *args)¶
Await a callback if it is a coroutine, else execute it.
- Return type
Any
Callback Groups¶
- class rclpy.callback_groups.CallbackGroup¶
The base class for a callback group.
A callback group controls when callbacks are allowed to be executed.
This class should not be instantiated. Instead, classes should extend it and implement
can_execute()
,beginning_execution()
, andending_execution()
.- add_entity(entity)¶
Add an entity to the callback group.
- Parameters
entity – a subscription, timer, client, service, or waitable instance.
- Return type
None
- beginning_execution(entity)¶
Get permission for the callback from the group to begin executing an entity.
If this returns
True
thenCallbackGroup.ending_execution()
must be called after the callback has been executed.- Parameters
entity – a subscription, timer, client, service, or waitable instance.
- Return type
bool
- Returns
True
if the callback can be executed,False
otherwise.
- can_execute(entity)¶
Determine if an entity can be executed.
- Parameters
entity – a subscription, timer, client, service, or waitable instance.
- Return type
bool
- Returns
True
if the entity can be executed,False
otherwise.
- ending_execution(entity)¶
Notify group that a callback has finished executing.
- Parameters
entity – a subscription, timer, client, service, or waitable instance.
- Return type
None
- has_entity(entity)¶
Determine if an entity has been added to this group.
- Parameters
entity – a subscription, timer, client, service, or waitable instance.
- Return type
bool
- class rclpy.callback_groups.MutuallyExclusiveCallbackGroup¶
Allow only one callback to be executing at a time.
- beginning_execution(entity)¶
Get permission for the callback from the group to begin executing an entity.
If this returns
True
thenCallbackGroup.ending_execution()
must be called after the callback has been executed.- Parameters
entity – a subscription, timer, client, service, or waitable instance.
- Returns
True
if the callback can be executed,False
otherwise.
- can_execute(entity)¶
Determine if an entity can be executed.
- Parameters
entity – a subscription, timer, client, service, or waitable instance.
- Returns
True
if the entity can be executed,False
otherwise.
- ending_execution(entity)¶
Notify group that a callback has finished executing.
- Parameters
entity – a subscription, timer, client, service, or waitable instance.
- class rclpy.callback_groups.ReentrantCallbackGroup¶
Allow callbacks to be executed in parallel without restriction.
- beginning_execution(entity)¶
Get permission for the callback from the group to begin executing an entity.
If this returns
True
thenCallbackGroup.ending_execution()
must be called after the callback has been executed.- Parameters
entity – a subscription, timer, client, service, or waitable instance.
- Returns
True
if the callback can be executed,False
otherwise.
- can_execute(entity)¶
Determine if an entity can be executed.
- Parameters
entity – a subscription, timer, client, service, or waitable instance.
- Returns
True
if the entity can be executed,False
otherwise.
- ending_execution(entity)¶
Notify group that a callback has finished executing.
- Parameters
entity – a subscription, timer, client, service, or waitable instance.