synchros2.futures module

class synchros2.futures.FutureConvertible

Bases: Awaitable[T], Protocol[T]

An awaitable that is convertible to a future-like object.

__init__(*args, **kwargs)

as_future() → FutureLike[T]

Get future-like view.

class synchros2.futures.FutureLike

Bases: Awaitable[T], Protocol[T]

A future-like awaitable object.

Matches rclpy.task.Future and concurrent.futures.Future protocols.

__init__(*args, **kwargs)

add_done_callback(func: Callable[[FutureLike[T]], None]) → None

Add a callback to be scheduled as soon as the future is ready.

cancel() → None

Cancel future.

cancelled() → bool

Check if future was cancelled.

done() → bool

Check if future is ready.

exception() → Exception | None

Get future exception, if any.

result() → T

Get future result (may block).

class synchros2.futures.WaitResult

Bases: NamedTuple

Result of waiting for multiple futures.

A named tuple with ‘done’ and ‘not_done’ sets of futures.

static __new__(_cls, ok: bool, done: Set[FutureLike], not_done: Set[FutureLike])

Create new instance of WaitResult(ok, done, not_done)

done: Set[FutureLike]

Alias for field number 1

not_done: Set[FutureLike]

Alias for field number 2

ok: bool

Alias for field number 0

synchros2.futures.as_proper_future(instance: FutureLike | FutureConvertible) → FutureLike

Return instance as a proper future-like object.

synchros2.futures.unwrap_future(future: FutureLike | FutureConvertible, timeout_sec: float | None = None, *, clock: rclpy.clock.Clock | None = None, context: rclpy.context.Context | None = None) → Any

synchros2.futures.unwrap_future(future: Iterable[FutureLike | FutureConvertible], timeout_sec: float | None = None, *, clock: rclpy.clock.Clock | None = None, context: rclpy.context.Context | None = None, strict: bool = False) → Iterator[Any]

Fetch future result(s) when done.

For a single future, blocks until the future is done and returns its result. For multiple futures, returns a generator that yields results as futures complete (like concurrent.futures.as_completed).

Note: This function may block and may raise if a future raises or it times out waiting. See wait_for_future() documentation for further reference on arguments.

Parameters:

• future – A single future or an iterable of futures

• timeout_sec – An optional timeout for how long to wait

• clock – An optional clock to use for timeout waits

• context – Current context (will use the default if none is given)

• strict – If True, yield results in order regardless of completion order. If False (default), yield results as they complete. Irrelevant when a single future is provided.

Returns:

the result(s) of the future(s) when they are done.

Raises:

ValueError – If timeout occurs before future(s) complete

Examples

Single future:

>>> result = unwrap_future(my_future, timeout_sec=5.0)

Multiple futures (non-strict, as completed):

>>> for result in unwrap_future([f1, f2, f3], timeout_sec=10.0):
...     process(result)

Multiple futures (strict, in order):

>>> for result in unwrap_future([f1, f2, f3], timeout_sec=10.0, strict=True):
...     process(result)

synchros2.futures.wait_and_return_result(future: FutureLike | FutureConvertible | Iterable[FutureLike | FutureConvertible], timeout_sec: float | None = None, *, clock: rclpy.clock.Clock | None = None, context: rclpy.context.Context | None = None, strict: bool = False) → Any | Iterator[Any]

Fetch future result when it is done.

Alias for unwrap_future().

synchros2.futures.wait_for_future(future: FutureLike | FutureConvertible, timeout_sec: float | None = None, *, clock: rclpy.clock.Clock | None = None, context: rclpy.context.Context | None = None) → WaitResult

synchros2.futures.wait_for_future(future: Iterable[FutureLike | FutureConvertible], timeout_sec: float | None = None, *, return_when: str = ALL_COMPLETED, clock: rclpy.clock.Clock | None = None, context: rclpy.context.Context | None = None) → WaitResult

Block while waiting for future(s) to become done.

Parameters:

• future – A single future or an iterable of futures to wait on

• timeout_sec – An optional timeout for how long to wait

• clock – An optional clock to use for timeout waits, defaults to the clock of the current scope if any, otherwise the system clock

• context – Current context (will use the default if none is given)

• return_when – One of FIRST_COMPLETED, FIRST_EXCEPTION, or ALL_COMPLETED. Only applies when waiting for multiple futures. Defaults to ALL_COMPLETED.

Returns:

A result object indicating which futures are done and which are not, and whether the wait was successful (i.e. not timed out).

Examples

Single future:

>>> result = wait_for_future(my_future, timeout_sec=5.0)
>>> if result:
...     value = my_future.result()

Multiple futures:

>>> result = wait_for_future([f1, f2, f3], return_when=FIRST_COMPLETED)
>>> for future in result.done:
...     print(future.result())