rclpy.executors module

exception rclpy.executors.ConditionReachedException

Bases: Exception

Future has been completed.

class rclpy.executors.Executor(*, context: Context | None = None)

Bases: object

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 – The context to be associated with, or None for the default global context.

add_node(node: Node) → bool

Add a node whose callbacks should be managed by this executor.

Parameters:

node – The node to add to the executor.

Returns:

True if the node was added, False otherwise.

can_execute(entity: WaitableEntityType) → bool

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, False otherwise.

property context: Context

Get the context associated with the executor.

create_task(callback: Callable | Coroutine, *args, **kwargs) → Task

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 – A callback to be run in the executor.

get_nodes() → List[Node]

Return nodes that have been added to this executor.

remove_node(node: Node) → None

Stop managing this node’s callbacks.

Parameters:

node – The node to remove from the executor.

shutdown(timeout_sec: float | None = None) → bool

Stop executing callbacks and wait for their completion.

Parameters:

timeout_sec – Seconds to wait. Block forever if None or negative. Don’t wait if 0.

Returns:

True if all outstanding callbacks finished executing, or False if the timeot expires before all outstanding work is done.

spin() → None

Execute callbacks until shutdown.

spin_once(timeout_sec: float | None = None) → None

Wait for and execute a single callback.

A custom executor should use wait_for_ready_callbacks() to get work.

Parameters:

timeout_sec – Seconds to wait. Block forever if None or negative. Don’t wait if 0.

spin_once_until_future_complete(future: Future, timeout_sec: float | TimeoutObject | None = None) → 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 – The executor will wait until this future is done.

  • timeout_sec – Maximum seconds to wait. Block forever if None or negative. Don’t wait if 0.

spin_until_future_complete(future: Future, timeout_sec: float | None = None) → None

Execute callbacks until a given future is done or a timeout occurs.

wait_for_ready_callbacks(*args, **kwargs) → Tuple[Task, WaitableEntityType, Node]

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: float | ~rclpy.executors.TimeoutObject | None = None, nodes: ~typing.List[Node] = None, condition: ~typing.Callable[[], bool] = <function Executor.<lambda>>) → Generator[Tuple[Task, WaitableEntityType, Node], None, None]

Yield callbacks that are ready to be executed.

Raises:
Parameters:

  • timeout_sec – Seconds to wait. Block forever if None or negative. Don’t wait if 0.

  • nodes – A list of nodes to wait on. Wait on all nodes if None.

  • condition – A callable that makes the function return immediately when it evaluates to True.

wake() → None

Wake the executor because something changed.

This is used to tell the executor when entities are created or destroyed.

exception rclpy.executors.ExternalShutdownException

Bases: Exception

Context has been shutdown.

class rclpy.executors.MultiThreadedExecutor(num_threads: int | None = None, *, context: Context | None = None)

Bases: Executor

Runs callbacks in a pool of threads.

Parameters:

  • num_threads – number of worker threads in the pool. If None, the number of threads will be automatically set by querying the underlying OS for the CPU affinity of the process space. If the OS doesn’t provide this information, defaults to 2.

  • context – The context associated with the executor.

spin_once(timeout_sec: float | None = None) → None

Wait for and execute a single callback.

A custom executor should use wait_for_ready_callbacks() to get work.

Parameters:

timeout_sec – Seconds to wait. Block forever if None or negative. Don’t wait if 0.

spin_once_until_future_complete(future: Future, timeout_sec: float | TimeoutObject | None = None) → 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 – The executor will wait until this future is done.

  • timeout_sec – Maximum seconds to wait. Block forever if None or negative. Don’t wait if 0.

exception rclpy.executors.ShutdownException

Bases: Exception

Signal that executor was shut down.

class rclpy.executors.SingleThreadedExecutor(*, context: Context | None = None)

Bases: Executor

Runs callbacks in the thread that calls Executor.spin().

spin_once(timeout_sec: float | None = None) → None

Wait for and execute a single callback.

A custom executor should use wait_for_ready_callbacks() to get work.

Parameters:

timeout_sec – Seconds to wait. Block forever if None or negative. Don’t wait if 0.

spin_once_until_future_complete(future: Future, timeout_sec: float | TimeoutObject | None = None) → 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 – The executor will wait until this future is done.

  • timeout_sec – Maximum seconds to wait. Block forever if None or negative. Don’t wait if 0.

exception rclpy.executors.TimeoutException

Bases: Exception

Signal that a timeout occurred.

class rclpy.executors.TimeoutObject(timeout: float)

Bases: object

Use timeout object to save timeout.

property timeout
async rclpy.executors.await_or_execute(callback: Callable | Coroutine, *args) → Any

Await a callback if it is a coroutine, else execute it.