Improve documentation.

[pyutils.git] / docs / pyutils.parallelize.rst

diff --git a/docs/pyutils.parallelize.rst b/docs/pyutils.parallelize.rst
index c53882d361bb8b0872e7e2b7155ab01fa0b7b099..32cdc255a0753b79f53dc9d4128d9caba7ee60d0 100644 (file)
--- a/docs/pyutils.parallelize.rst
+++ b/docs/pyutils.parallelize.rst
@@ -7,6 +7,8 @@ Submodules
 pyutils.parallelize.deferred\_operand module
 --------------------------------------------
 
+DeferredOperand is the base class for SmartFuture.
+
 .. automodule:: pyutils.parallelize.deferred_operand
    :members:
    :undoc-members:
@@ -15,6 +17,13 @@ pyutils.parallelize.deferred\_operand module
 pyutils.parallelize.executors module
 ------------------------------------
 
+This module defines three executors: one for threads in the same
+process, one for separate processes on the same machine and the third
+for separate processes on remote machines.  Each can be used via the
+@parallelize decorator.  These executor pools are automatically
+cleaned up at program exit.
+
+
 .. automodule:: pyutils.parallelize.executors
    :members:
    :undoc-members:
@@ -23,6 +32,8 @@ pyutils.parallelize.executors module
 pyutils.parallelize.parallelize module
 --------------------------------------
 
+This module defines a decorator that can be used for simple parallelization.
+
 .. automodule:: pyutils.parallelize.parallelize
    :members:
    :undoc-members:
@@ -31,6 +42,16 @@ pyutils.parallelize.parallelize module
 pyutils.parallelize.smart\_future module
 ----------------------------------------
 
+Defines a SmartFuture class that is part of the parallelization
+framework.  A SmartFuture is a kind of Future (i.e. a representation
+of the result of asynchronous processing that may know its value or
+not depending on whether the asynchronous operation has completed).
+Whereas normal Python Futures must be waited on or resolved manually,
+a SmartFuture automatically waits for its result to be known as soon
+as it is utilized in an expression that demands its value.
+
+Also contains some utilility code for waiting for one/many futures.
+
 .. automodule:: pyutils.parallelize.smart_future
    :members:
    :undoc-members:
@@ -39,6 +60,8 @@ pyutils.parallelize.smart\_future module
 pyutils.parallelize.thread\_utils module
 ----------------------------------------
 
+Simple utils that deal with threads.
+
 .. automodule:: pyutils.parallelize.thread_utils
    :members:
    :undoc-members:
@@ -47,6 +70,11 @@ pyutils.parallelize.thread\_utils module
 Module contents
 ---------------
 
+This module contains a framework for easy Python parallelization.  To
+see an example of how it is used, look at examples/wordle/...
+
+This module also contains some utilities that deal with parallelization.
+
 .. automodule:: pyutils.parallelize
    :members:
    :undoc-members: