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)

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 define shutdown().

Parameters

context (Optional[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.

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

Get the context associated with the executor.

Return type

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 (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 if None or negative. Don’t wait if 0.

Return type

bool

Returns

True if all outstanding callbacks finished executing, or False 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 if None 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)

Yield callbacks that are ready to be executed.

Raises
Parameters
  • timeout_sec (float) – Seconds to wait. Block forever if None or negative. Don’t wait if 0.

  • nodes (List[ForwardRef]) – A list of nodes to wait on. Wait on all nodes if None.

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. If None, the number of threads will use multiprocessing.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 if None 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 if None 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(), and ending_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 then CallbackGroup.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 then CallbackGroup.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 then CallbackGroup.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.