Minor improvements to the threading introduction:
* Expand the example to show a join.
* Mention the use case of I/O running concurrent with a computational
thread.
* Be a tad more forceful about recommending Queue over other approaches
to synchonization.
* Eliminate discussion around having a single interpreter. This is a
more advanced discussion that belongs in the library reference and
in a section on extending and embedding.
diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex
index 978db65..970c8ad 100644
--- a/Doc/tut/tut.tex
+++ b/Doc/tut/tut.tex
@@ -4868,12 +4868,12 @@
\section{Multi-threading\label{multi-threading}}
Threading is a technique for decoupling tasks which are not sequentially
-dependent. Python threads are driven by the operating system and run
-in a single process and share memory space in a single interpreter.
+dependent. Threads can be used to improve the responsiveness of
+applications that accept user input while other tasks run in the
+background. A related use case is running I/O in parallel with
+computations in another thread.
-Threads can be used to improve the responsiveness of applications that
-accept user input while other tasks run in the background. The
-following code shows how the high level
+The following code shows how the high level
\ulink{\module{threading}}{../lib/module-threading.html} module can run
tasks in background while the main program continues to run:
@@ -4891,8 +4891,12 @@
f.close()
print 'Finished background zip of: ', self.infile
- AsyncZip('mydata.txt', 'myarchive.zip').start()
- print 'The main program continues to run'
+ background = AsyncZip('mydata.txt', 'myarchive.zip')
+ background.start()
+ print 'The main program continues to run in foreground.'
+
+ background.join() # Wait for the background task to finish
+ print 'Main program waited until background was done.'
\end{verbatim}
The principal challenge of multi-threaded applications is coordinating
@@ -4901,13 +4905,13 @@
events, condition variables, and semaphores.
While those tools are powerful, minor design errors can result in
-problems that are difficult to reproduce. A simpler and more robust
-approach to task coordination is concentrating all access to a resource
+problems that are difficult to reproduce. So, the preferred approach
+to task coordination is to concentrate all access to a resource
in a single thread and then using the
\ulink{\module{Queue}}{../lib/module-Queue.html} module to feed that
-thread with requests from other threads. Applications that use
+thread with requests from other threads. Applications using
\class{Queue} objects for inter-thread communication and coordination
-tend to be easier to design, more readable, and more reliable.
+are easier to design, more readable, and more reliable.
\section{Logging\label{logging}}