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 define Executor.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