From: Scott Gasch <scott@gasch.org>
Date: Sun, 30 Oct 2022 20:50:50 +0000 (-0700)
Subject: Update docs.
X-Git-Url: https://wannabe.guru.org/gitweb/?a=commitdiff_plain;h=38b139bc6d720b52765b6058d90752427a6a7e56;p=pyutils.git

Update docs.
---

diff --git a/docs/pyutils.collectionz.rst b/docs/pyutils.collectionz.rst
index 0b01237..5ca878d 100644
--- a/docs/pyutils.collectionz.rst
+++ b/docs/pyutils.collectionz.rst
@@ -1,9 +1,12 @@
 pyutils.collectionz package
 ===========================
 
-This subpackage contains some homegrown collections that try to emulate
-:mod:`collections` included in the Python standard library.  It ends
-with a 'z' so as not to collide with the standard library package.
+This subpackage contains some homegrown collections that try to
+emulate :mod:`collections` included in the Python standard library
+(see:
+https://docs.python.org/3/library/collections.html#module-collections).
+It ends with a 'z' so as not to collide with the standard library
+package.
 
 Submodules
 ----------
diff --git a/src/pyutils/parallelize/parallelize.py b/src/pyutils/parallelize/parallelize.py
index 515d431..7071ef3 100644
--- a/src/pyutils/parallelize/parallelize.py
+++ b/src/pyutils/parallelize/parallelize.py
@@ -12,10 +12,12 @@ remote machine depending on the style of decoration::
     def my_function(a, b, c) -> int:
         ...do some slow / expensive work, e.g., an http request
 
+    # Run with background subprocess
     @p.parallelize(method=Method.PROCESS)
     def my_other_function(d, e, f) -> str:
         ...do more really expensive work, e.g., a network read
 
+    # Run in a helper process on another machine.
     @p.parallelize(method=Method.REMOTE)
     def my_other_other_function(g, h) -> int:
         ...this work will be distributed to a remote machine pool
@@ -72,6 +74,31 @@ do some setup work:
     If you're trying to set this up and struggling, email me at
     scott.gasch@gmail.com.  I'm happy to help.
 
+    What you get back when you call a decorated message is a
+    :class:`pyutils.parallelize.smart_future.SmartFuture`.  This class
+    attempts to transparently wrap a normal Python :class:`Future`
+    (see
+    https://docs.python.org/3/library/concurrent.futures.html#future-objects).
+    If your code just uses the result of a `parallelized` method it
+    will block waiting on the result of the method as soon as it uses
+    the result in a manner that requires its value to be known
+    (e.g. using it in an expression, calling a method on it, hashing
+    it, etc...)  But you can do operations that do not require the
+    value to be known (e.g. storing it in a list, storing it as a
+    value in a dict, etc...) without blocking.
+
+    There are two helper methods in
+    :mod:`pyutils.parallelize.smart_future` to help deal with these
+    :class:`SmartFuture` objects called
+    :meth:`pyutils.parallelize.smart_future.wait_all` and
+    :meth:`pyutils.parallelize.smart_future.wait_any`.  These, when
+    given a collection of :class:`SmartFuture` objects,
+    will block until one (any) or all (all) are finished and yield the
+    finished objects to the caller.  Callers can be confident that any
+    objects returned from these methods will not block when accessed.
+    See documentation in :mod:`pyutils.parallelize.smart_future` for
+    more details.
+
 """
 
 import atexit
diff --git a/src/pyutils/parallelize/smart_future.py b/src/pyutils/parallelize/smart_future.py
index 8ac05f1..b722cfe 100644
--- a/src/pyutils/parallelize/smart_future.py
+++ b/src/pyutils/parallelize/smart_future.py
@@ -50,7 +50,7 @@ def wait_any(
             futures completes
         log_exceptions: Should we log (warning + exception) any
             underlying exceptions raised during future processing or
-            silently ignore then?
+            silently ignore them?
         timeout: invoke callback with a periodicity of timeout while
             awaiting futures
 
@@ -105,7 +105,7 @@ def wait_all(
         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?
+            silently ignore them?
 
     Returns:
         Only when all futures in the input list are ready.  Blocks