# HG changeset patch
# User paulb
# Date 1189871838 0
# Node ID e267c093f6884c7af654c3b31b86a9f9d3f8c9e3
# Parent  f6d1181d2bb293a314caae3e28053f4bc277998e
[project @ 2007-09-15 15:57:18 by paulb]
Added much more information about the extended examples.

diff -r f6d1181d2bb2 -r e267c093f688 README.txt
--- a/README.txt	Sat Sep 15 15:46:26 2007 +0000
+++ b/README.txt	Sat Sep 15 15:57:18 2007 +0000
@@ -10,23 +10,54 @@
 Quick Start
 -----------
 
-Try running the simple examples:
+Try running the simple examples. For example:
 
-PYTHONPATH=. python examples/simple.py
 PYTHONPATH=. python examples/simple_create.py
-PYTHONPATH=. python examples/simple_managed.py
-PYTHONPATH=. python examples/simple_map.py
-PYTHONPATH=. python examples/simple_pmap.py
-PYTHONPATH=. python examples/simple_queue.py
+
+(These examples show in different ways how limited number of processes can be
+used to perform a parallel computation. The simple.py and simple_map.py
+programs are sequential versions of the other programs.)
+
+The following table summarises the features used in the programs:
+
+Program (.py)           pmap  MakeParallel manage start create Queue Exchange
+-------------           ----  ------------ ------ ----- ------ ----- --------
+simple   
+simple_create                                           Yes          Yes
+simple_create_queue                                     Yes    Yes
+simple_managed                Yes          Yes                       Yes
+simple_managed_queue          Yes          Yes                 Yes
+simple_map   
+simple_pmap             Yes
+simple_start                                      Yes                Yes
+simple_start_queue            Yes                 Yes          Yes
 
-(A simple example which shows how a limited number of processes can be used to
-perform a parallel computation. The simple_map.py program is a sequential
-version of the other programs.)
+The simplest parallel program is simple_pmap.py which employs the pmap
+function resembling the built-in map function in Python.
+
+Other simple programs are those employing the Queue class, together with those
+using the manage method which associates functions or callables with Queue or
+Exchange objects for convenient invocation of those functions and the
+management of their communications.
+
+The most technically involved program is simple_start.py which uses the
+Exchange class together with a calculation function which is aware of the
+parallel environment and which communicates over the supplied communications
+channel directly to the creating process.
+
+It should be noted that with the exception of simple_start.py, those examples
+employing calculation functions (as opposed to doing a calculation inline in a
+loop body) all use MakeParallel to make those functions parallel-aware, thus
+permitting the conversion of "normal" functions to a form usable in the
+parallel environment.
 
 The tutorial provides some information about the examples: docs/tutorial.xhtml
 
+Parallel Raytracing with PyGmy
+------------------------------
+
 The PyGmy raytracer modified to use pprocess can be run to investigate the
-potential for speed increases:
+potential for speed increases in "real world" programs:
 
 cd examples/PyGmy
 PYTHONPATH=../..:. python scene.py
@@ -34,6 +65,9 @@
 (This should produce a file called test.tif - a TIFF file containing a
 raytraced scene image.)
 
+Test Programs
+-------------
+
 There are some elementary tests:
 
 PYTHONPATH=. python tests/create_loop.py
@@ -88,7 +122,7 @@
     new processes beyond the process limit: such requests are queued and
     performed as running processes are completed. This permits programs using
     the start method to proceed to consumption of results more quickly.
-  * Extended and updated the examples.
+  * Extended and updated the examples. Added a tutorial.
   * Added Ubuntu Feisty (7.04) package support.
 
 New in parallel 0.2.5 (Changes since parallel 0.2.4)