# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1443192039 -7200
# Node ID 2cd56ed1e0f7fa6aed00c42b7f271b50d059faf8
# Parent  1a159a412b8b2db39e4c45dd77ad5ae19f8222b4
Added a note about data exchange between processes and the differences to
"normal" Python.

diff -r 1a159a412b8b -r 2cd56ed1e0f7 docs/tutorial.html
--- a/docs/tutorial.html	Fri Sep 25 16:02:56 2015 +0200
+++ b/docs/tutorial.html	Fri Sep 25 16:40:39 2015 +0200
@@ -16,6 +16,7 @@
 use the <code>pmap</code> function.</p>
 
 <ul>
+<li><a href="#note">A Note on Parallel Processes</a></li>
 <li><a href="#pmap">Converting Map-Style Code</a></li>
 <li><a href="#Map">Converting Invocations to Parallel Operations</a></li>
 <li><a href="#Queue">Converting Arbitrarily-Ordered Invocations</a>
@@ -35,6 +36,81 @@
 <p>For a brief summary of each of the features of <code>pprocess</code>, see
 the <a href="reference.html">reference document</a>.</p>
 
+<h2 id="note">A Note on Parallel Processes</h2>
+
+<p>The way <code>pprocess</code> uses multiple processes to perform work in
+parallel involves the <code>fork</code> system call, which on modern operating
+systems involves what is known as "copy-on-write" semantics. In plain language,
+when <code>pprocess</code> creates a new <em>child</em> process to perform work
+in parallel with other work that needs to be done, this new process will be a
+near-identical copy of the original <em>parent</em> process, and the running
+code will be able to access data resident in that parent process.</p>
+
+<p>However, when a child process modifies data, instead of changing that data
+in such a way that the parent process can see the modifications, the parent
+process will, in fact, remain oblivious to such changes. What happens is that
+as soon as the child process attempts to modify the data, it obtains its own
+separate copy which is then modified independently of the original data. Thus,
+a <em>copy</em> of any data is made when an attempt is made to <em>write</em>
+to such data. Meanwhile, the parent's copy of that data will be left untouched
+by the activities of the child.</p>
+
+<p>It is therefore essential to note that any data distributed to other
+processes, and which will then be modified by those processes, will not appear
+to change in the parent process even if the objects employed are mutable. This
+is rather different to the behaviour of a normal Python program: passing a
+list to a function, for example, mutates that list in such a way that upon
+returning from that function the modifications will still be present. For
+example:</p>
+
+<pre>
+def mutator(l):
+    l.append(3)
+
+l = [1, 2]
+mutator(l) # l is now [1, 2, 3]
+</pre>
+
+<p>In contrast, passing a list to a child process will cause the list to
+mutate in the child process, but the parent process will not see the list
+change. For example:</p>
+
+<pre>
+def mutator(l):
+    l.append(3)
+
+results = pprocess.Map()
+mutator = results.manage(pprocess.MakeParallel(mutator))
+
+l = [1, 2]
+mutator(l) # l is now [1, 2]
+</pre>
+
+<p>To communicate changes to data between processes, the modified objects must
+be explicitly returned from child processes using the mechanisms described in
+this documentation. For example:</p>
+
+<pre>
+def mutator(l):
+    l.append(3)
+    return l       # the modified object is explicitly returned
+
+results = pprocess.Map()
+mutator = results.manage(pprocess.MakeParallel(mutator))
+
+l = [1, 2]
+mutator(l)
+
+all_l = results[:] # there are potentially many results, not just one
+l = all_l[0]       # l is now [1, 2, 3], taken from the first result
+</pre>
+
+<p>It is perhaps easiest to think of the communications mechanisms as
+providing a gateway between processes through which information can be passed,
+with the rest of a program's data being private and hidden from the other
+processes (even if that data initially resembles what the other processes also
+see within themselves).</p>
+
 <h2 id="pmap">Converting Map-Style Code</h2>
 
 <p>Consider a program using the built-in <code>map</code> function and a sequence of inputs:</p>