# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1439976684 -7200
# Node ID af9d597d97ecef240d74a5011c6027e18aa85480
# Parent  959df6d0d1b25a85bec2a2e576f4f96de9025271
Added examples and notes about mutable objects.

diff -r 959df6d0d1b2 -r af9d597d97ec README.txt
--- a/README.txt	Sun Jan 05 00:56:40 2014 +0100
+++ b/README.txt	Wed Aug 19 11:31:24 2015 +0200
@@ -7,6 +7,12 @@
 systems with multiple CPUs or multicore CPUs, processes should take advantage
 of as many CPUs or cores as the operating system permits.
 
+Since pprocess distributes work to other processes, certain aspects of the
+behaviour of those processes may differ from the normal behaviour of such
+code. For example, any mutable objects distributed to other processes can
+still be modified, but any modifications will not be visible outside the
+processes making such modifications. The 
+
 Tutorial
 --------
 
@@ -123,6 +129,22 @@
 PYTHONPATH=. python examples/concurrency-sig/bottles.py
 PYTHONPATH=. python examples/concurrency-sig/bottles_heartbeat.py
 
+Examples of Modifying Mutable Objects
+-------------------------------------
+
+Mutable objects can be modified in processes created by pprocess, but the
+modifications will not be visible in the parent process. The following
+examples illustrate the problem:
+
+PYTHONPATH=. python examples/simple_mutable.py
+PYTHONPATH=. python examples/simple_mutable_queue.py
+
+The former, non-parallel program will display the expected result of the
+computation, whereas the latter, parallel program will fail to do so. This is
+because the latter attempts to modify the input collection in order to use it
+as a result collection, but these modifications are not propagated back to the
+parent process.
+
 Test Programs
 -------------
 
@@ -167,6 +189,12 @@
 available only on "UNIX"; it has only been tested repeatedly on a GNU/Linux
 system, and occasionally on systems running OpenSolaris.
 
+New in pprocess 0.5.2 (Changes since pprocess 0.5.1)
+----------------------------------------------------
+
+  * Added examples involving mutable objects and the inability of pprocess to
+    automatically propagate changes to such objects back to parent processes.
+
 New in pprocess 0.5.1 (Changes since pprocess 0.5)
 --------------------------------------------------
 
diff -r 959df6d0d1b2 -r af9d597d97ec examples/simple_mutation.py
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/examples/simple_mutation.py	Wed Aug 19 11:31:24 2015 +0200
@@ -0,0 +1,54 @@
+#!/usr/bin/env python
+
+"""
+A simple example of sequential computation using a function, attempting to
+modify a list/array.
+"""
+
+import time
+#import random
+
+# Array size.
+
+N = 10
+delay = 1
+
+# Work function.
+
+def calculate(results, i, j):
+
+    """
+    A supposedly time-consuming calculation on 'results' using 'i' and 'j'.
+    """
+
+    #time.sleep(delay * random.random())
+    time.sleep(delay)
+    results[i * N + j] *= 2
+
+# Main program.
+
+if __name__ == "__main__":
+
+    t = time.time()
+
+    # Initialise an array.
+
+    results = range(0, 100)
+
+    # Perform the work.
+
+    print "Calculating..."
+    for i in range(0, N):
+        for j in range(0, N):
+            calculate(results, i, j)
+
+    # Show the results.
+
+    for i in range(0, N):
+        for result in results[i*N:i*N+N]:
+            print result,
+        print
+
+    print "Time taken:", time.time() - t
+
+# vim: tabstop=4 expandtab shiftwidth=4
diff -r 959df6d0d1b2 -r af9d597d97ec examples/simple_mutation_queue.py
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/examples/simple_mutation_queue.py	Wed Aug 19 11:31:24 2015 +0200
@@ -0,0 +1,59 @@
+#!/usr/bin/env python
+
+"""
+A simple example of sequential computation using a function, attempting to
+modify a list/array.
+"""
+
+import pprocess
+import time
+#import random
+
+# Array size.
+
+N = 10
+limit = 10
+delay = 1
+
+# Work function.
+
+def calculate(results, i, j):
+
+    """
+    A supposedly time-consuming calculation on 'results' using 'i' and 'j'.
+    """
+
+    #time.sleep(delay * random.random())
+    time.sleep(delay)
+    results[i * N + j] *= 2
+
+# Main program.
+
+if __name__ == "__main__":
+
+    t = time.time()
+
+    queue = pprocess.Queue(limit=limit)
+    calc = queue.manage(pprocess.MakeParallel(calculate))
+
+    # Initialise an array.
+
+    results = range(0, 100)
+
+    # Perform the work.
+
+    print "Calculating..."
+    for i in range(0, N):
+        for j in range(0, N):
+            calc(results, i, j)
+
+    # Show the results.
+
+    for i in range(0, N):
+        for result in results[i*N:i*N+N]:
+            print result,
+        print
+
+    print "Time taken:", time.time() - t
+
+# vim: tabstop=4 expandtab shiftwidth=4