delegate.py - delegation of work to multiple processes
Ka-Ping Yee, 15 December 1999
 
This module provides generic mechanisms for delegating work items.
At the moment, the main delegation mechanism is running work items in
parallel in child processes.  Call 'parallelize' with a function and a
list of items to start the work.  Here is an example:
 
    def work(arg): return arg * 3
    
    from delegate import parallelize
    print parallelize(work, [2, 5, "a", 7])
 
The function must return a value that can be pickled so that it can be
communicated back to the parent.  Most kinds of Python objects can be
pickled, including instances of custom classes as long as the class
allows the __init__ constructor to be called with no arguments.  See
the 'pickle' module for details.  The results are returned in a
dictionary that maps each item to its result.
 
The 'parallelize' function accepts an optional 'reporter' parameter
with which you can provide callbacks when jobs start and finish.  See
the documentation on 'parallelize' and the Reporter class for details.
 
The 'timeout' function will run a job in a child process in order to
limit its running time.  Here is an example:
 
    import time
    def work():
        time.sleep(10)
        return 5
 
    from delegate import timeout
    print timeout(work, 30)             # this will print 5 after 10 seconds
    print timeout(work, 5)              # this will print None after 5 seconds
 
See the documentation string on 'timeout' for details.

Modules
		cPickle os cPickle select signal sys traceback

Classes
		Exception IdPrinter Parallelizer PipeReader Reporter LogReporter TerminalReporter   class Exception       Class for passing on exceptions raised in child processes.      __init__(self, type, value, tbdump='') __repr__(self)   class IdPrinter            __init__(self, maxrows) delid(self, id) delrow(self, row) printid(self, id, text) printrow(self, row, text)   class LogReporter(Reporter)       A reporter that prints out status line-by-line.      abort(self, pid, item) begin(self, pid, item) cleanup(self) exit(self, pid) fail(self, pid, item, exception) init(self, children) spawn(self, pid) success(self, pid, item, result)   class Parallelizer       Class for maintaining the state of work being done in parallel. Usually, the parallelize() function in this module is sufficient; if you want to use this class directly, then:       1. Create a Parallelizer object by passing in the work        function and the optional Reporter object to the        Parallelizer() constructor.       2. Call the 'spawn(children)' method to spawn the specified        number of child processes.       3. Call the 'process(items)' method with a list of items to        process.  You can do this as many times as you want.             4. Be sure to call the 'cleanup()' method to clean away the        child processes when you are done.       5. Repeat steps 2 through 4 if you want to spawn more        children and collect more results.  The results accrue        in a dictionary in the 'results' attribute.      __init__(self, function, reporter=<delegate.Reporter instance>) child(self, reader, writer) cleanup(self) process(self, items) spawn(self, children)   class PipeReader       A file-like read-only interface to a file descriptor.      __init__(self, fd) read(self, bytes) readline(self)   class Reporter       Abstract base class for Reporter objects.  To handle callbacks during processing, declare your own Reporter object that implements these methods.      abort(self, pid, item) Called by the Parallelizer when a child terminates unexpectedly. begin(self, pid, item) Called by the Parallelizer when a child starts work on an item. cleanup(self) Called by the Parallelizer when child processes are cleaned up. exit(self, pid) Called by the Parallelizer when a child terminates. fail(self, pid, item, exception) Called by the Parallelizer when a child raises an exception. init(self, children) Called by the Parallelizer just before processes are spawned. spawn(self, pid) Called by the Parallelizer for each individual child spawned. success(self, pid, item, result) Called by the Parallelizer when a child produces a result.   class TerminalReporter(Reporter)       A reporter that displays animated status on an ANSI terminal.      abort(self, pid, item) begin(self, pid, item) cleanup(self) exit(self, pid) fail(self, pid, item, exception) init(self, children) spawn(self, pid) success(self, pid, item, result)

Functions
		failsafe(function, *args, **kw) Run the function with the given arguments and keyword arguments, returning the function's return value.  In the event of any exception, catch it and return None. parallelize(function, items, children=6, reporter=<delegate.Reporter instance>) Run the given function on each member in the 'items' list in parallel, and return a dictionary that maps each item to the result returned by the function.  The return value of the function must be picklable so that it can be communicated from the child process to the parent.  If an exception is raised by the function, the result dictionary will map the item to an Exception object containing the exception's type and value and a string with a printout of the traceback.   The number of child processes to be spawned is determined by 'children'. The optional 'reporter' argument provides a Reporter object to receive callbacks as the work proceeds.  See the definition of the Reporter class for the interface it should provide. pipedump(object, fd) Pickle an object to the stream given by a numeric descriptor. pipeload(fd) Unpickle an object from the stream given by a numeric descriptor. reap() Reap any defunct child processes. suicide() Terminate this process.  Unlike sys.exit(), which raises a SystemExit exception that might be caught, this routine kills the current process. Spawned children must exit this way because exceptions must not be allowed to escape to code beyond the fork(), which would cause great confusion. timeout(function, time=2) Run the given function in a child process and return its return value. If it raises an exception, return an Exception object containing the exception's type and value and a string with a printout of the traceback. If the function doesn't return within the given number of seconds, kill it and return None.

Data
		BEGIN = 2 EXIT = 3 FAIL = 1 SUCCESS = 0 __file__ = './delegate.pyc' __name__ = 'delegate'