#!/usr/bin/env python3
-"""A future that can be treated like the result that it contains and
-will not block until it is used. At that point, if the underlying
-value is not yet available, it will block until it becomes
-available."""
+# © Copyright 2021-2022, Scott Gasch
-from __future__ import annotations
+"""A :class:Future that can be treated as a substutute for the result
+that it contains and will not block until it is used. At that point,
+if the underlying value is not yet available yet, it will block until
+the internal result actually becomes available.
+"""
+from __future__ import annotations
import concurrent
import concurrent.futures as fut
import logging
callback: Callable = None,
log_exceptions: bool = True,
):
+ """Await the completion of any of a collection of SmartFutures and
+ invoke callback each time one completes, repeatedly, until they are
+ all finished.
+
+ Args:
+ futures: A collection of SmartFutures to wait on
+ callback: An optional callback to invoke whenever one of the
+ futures completes
+ log_exceptions: Should we log (warning + exception) any
+ underlying exceptions raised during future processing or
+ silently ignore then?
+ """
+
real_futures = []
smart_future_by_real_future = {}
completed_futures: Set[fut.Future] = set()
*,
log_exceptions: bool = True,
) -> None:
+ """Wait for all of the SmartFutures in the collection to finish before
+ returning.
+
+ Args:
+ futures: A collection of futures that we're waiting for
+ log_exceptions: Should we log (warning + exception) any
+ underlying exceptions raised during future processing or
+ silently ignore then?
+ """
+
real_futures = []
for x in futures:
assert isinstance(x, SmartFuture)
class SmartFuture(DeferredOperand):
- """This is a SmartFuture, a class that wraps a normal Future and can
- then be used, mostly, like a normal (non-Future) identifier.
+ """This is a SmartFuture, a class that wraps a normal :class:`Future`
+ and can then be used, mostly, like a normal (non-Future)
+ identifier of the type of that SmartFuture's result.
Using a FutureWrapper in expressions will block and wait until
the result of the deferred operation is known.