X-Git-Url: https://wannabe.guru.org/gitweb/?a=blobdiff_plain;f=smart_future.py;h=625c3ed66b63b3ec17e5dc94897a3ca1a88a5451;hb=e46158e49121b8a955bb07b73f5bcf9928b79c90;hp=a1f6d97741db715871d404d5a126d87a5601b503;hpb=f2600f30801c849fc1d139386e3ddc3c9eb43e30;p=python_utils.git

diff --git a/smart_future.py b/smart_future.py
index a1f6d97..625c3ed 100644
--- a/smart_future.py
+++ b/smart_future.py
@@ -1,9 +1,12 @@
 #!/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
+
+"""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
@@ -29,7 +32,23 @@ def wait_any(
     *,
     callback: Callable = None,
     log_exceptions: bool = True,
+    timeout: float = None,
 ):
+    """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?
+        timeout: invoke callback with a periodicity of timeout while
+            awaiting futures
+    """
+
     real_futures = []
     smart_future_by_real_future = {}
     completed_futures: Set[fut.Future] = set()
@@ -39,18 +58,24 @@ def wait_any(
         smart_future_by_real_future[x.wrapped_future] = x
 
     while len(completed_futures) != len(real_futures):
-        newly_completed_futures = concurrent.futures.as_completed(real_futures)
-        for f in newly_completed_futures:
+        try:
+            newly_completed_futures = concurrent.futures.as_completed(real_futures, timeout=timeout)
+            for f in newly_completed_futures:
+                if callback is not None:
+                    callback()
+                completed_futures.add(f)
+                if log_exceptions and not f.cancelled():
+                    exception = f.exception()
+                    if exception is not None:
+                        logger.warning(
+                            'Future 0x%x raised an unhandled exception and exited.', id(f)
+                        )
+                        logger.exception(exception)
+                        raise exception
+                yield smart_future_by_real_future[f]
+        except TimeoutError:
             if callback is not None:
                 callback()
-            completed_futures.add(f)
-            if log_exceptions and not f.cancelled():
-                exception = f.exception()
-                if exception is not None:
-                    logger.warning('Future 0x%x raised an unhandled exception and exited.', id(f))
-                    logger.exception(exception)
-                    raise exception
-            yield smart_future_by_real_future[f]
     if callback is not None:
         callback()
 
@@ -60,6 +85,16 @@ def wait_all(
     *,
     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)
@@ -81,8 +116,9 @@ def wait_all(
 
 
 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.