[py-svn] r36352 - in py/dist/py: test/testing thread

[hpk at codespeak.net]

Author: hpk
Date: Tue Jan  9 14:23:32 2007
New Revision: 36352

Modified:
   py/dist/py/test/testing/test_session.py
   py/dist/py/thread/io.py
   py/dist/py/thread/pool.py
Log:
adding docstrings to py/thread and
avoiding timeout issues for test_loop_on_failing 



Modified: py/dist/py/test/testing/test_session.py
==============================================================================
--- py/dist/py/test/testing/test_session.py	(original)
+++ py/dist/py/test/testing/test_session.py	Tue Jan  9 14:23:32 2007
@@ -389,7 +389,7 @@
         pool = py._thread.WorkerPool() 
         reply = pool.dispatch(session.main, [str(o)])
         while 1: 
-            s = out.get(timeout=2.0) 
+            s = out.get()
             if s.find('1 failed') != -1: 
                 break 
         else: 

Modified: py/dist/py/thread/io.py
==============================================================================
--- py/dist/py/thread/io.py	(original)
+++ py/dist/py/thread/io.py	Tue Jan  9 14:23:32 2007
@@ -2,6 +2,11 @@
 import thread
 
 class ThreadOut(object): 
+    """ A file like object that diverts writing operations 
+        to per-thread writefuncs.  
+        This is a py lib internal class and not meant for outer use
+        or modification. 
+    """
     def __new__(cls, obj, attrname): 
         """ Divert file output to per-thread writefuncs. 
             the given obj and attrname describe the destination 

Modified: py/dist/py/thread/pool.py
==============================================================================
--- py/dist/py/thread/pool.py	(original)
+++ py/dist/py/thread/pool.py	Tue Jan  9 14:23:32 2007
@@ -6,6 +6,10 @@
 ERRORMARKER = object() 
 
 class Reply(object): 
+    """ reply instances provide access to the result
+        of a function execution that got dispatched
+        through WorkerPool.dispatch() 
+    """
     _excinfo = None 
     def __init__(self, task): 
         self.task = task 
@@ -34,6 +38,11 @@
                 time.sleep(delay)       #reduce CPU usage by using a sleep
 
     def get(self, timeout=None): 
+        """ get the result object from an asynchronous function execution.
+            if the function execution raised an exception, 
+            then calling get() will reraise that exception
+            including its traceback. 
+        """
         if self._queue is None: 
             raise EOFError("reply has already been delivered")
         if timeout is not None: 
@@ -91,8 +100,22 @@
         self._queue.put(SystemExit)   
         
 class WorkerPool(object): 
+    """ A WorkerPool allows to dispatch function executions
+        to threads.  Each Worker Thread is reused for multiple
+        function executions. The dispatching operation 
+        takes care to create and dispatch to existing 
+        threads. 
+
+        You need to call shutdown() to signal 
+        the WorkerThreads to terminate and join() 
+        in order to wait until all worker threads
+        have terminated. 
+    """
     _shuttingdown = False 
     def __init__(self, maxthreads=None): 
+        """ init WorkerPool instance which may
+            create up to `maxthreads` worker threads. 
+        """
         self.maxthreads = maxthreads
         self._ready = {}
         self._alive = {}
@@ -120,12 +143,16 @@
         return thread 
 
     def shutdown(self): 
+        """ signal all worker threads to terminate. 
+            call join() to wait until all threads termination. 
+        """
         if not self._shuttingdown: 
             self._shuttingdown = True 
             for t in self._alive.keys(): 
                 t.stop() 
 
     def join(self, timeout=None): 
+        """ wait until all worker threads have terminated. """
         current = threading.currentThread()
         deadline = delta = None 
         if timeout is not None: