Merge branch 'tleonhardt-python_threads'

* tleonhardt-python_threads:
  Style fixes for Python threads documentation changes
  Finished updating Python docs for -threads option
  Started making changes to Python.html to document support for multithreaded Python SWIG applications.

Doc/Manual/Contents.html

@@ -1614,6 +1614,11 @@
 <li><a href="Python.html#Python_nn77">Byte string output conversion</a>
 <li><a href="Python.html#Python_2_unicode">Python 2 Unicode</a>
 </ul>
+<li><a href="Python.html#Python_multithreaded">Support for Multithreaded Applications</a>
+<ul>
+<li><a href="Python.html#Python_thread_UI">UI for Enabling Multithreading Support</a>
+<li><a href="Python.html#Python_thread_performance">Multithread Performance</a>
+</ul>
 </ul>
 </div>
 <!-- INDEX -->

Doc/Manual/Python.html

@@ -133,6 +133,11 @@
 <li><a href="#Python_nn77">Byte string output conversion</a>
 <li><a href="#Python_2_unicode">Python 2 Unicode</a>
 </ul>
+<li><a href="#Python_multithreaded">Support for Multithreaded Applications</a>
+<ul>
+<li><a href="#Python_thread_UI">UI for Enabling Multithreading Support</a>
+<li><a href="#Python_thread_performance">Multithread Performance</a>
+</ul>
 </ul>
 </div>
 <!-- INDEX -->
@@ -2961,9 +2966,6 @@ class MyFoo(mymodule.Foo):
 <H3><a name="Python_nn34">36.5.2 Director classes</a></H3>
 
 
- 
-
-
 <p>
 For each class that has directors enabled, SWIG generates a new class
 that derives from both the class in question and a special
@@ -6730,6 +6732,110 @@ the first is allowing unicode conversion and the second is explicitly
 prohibiting it.
 </p>
 
+<H2><a name="Python_multithreaded">36.13 Support for Multithreaded Applications</a></H2>
+
+
+<p>By default, SWIG does not enable support for multithreaded Python applications.  More
+specifically, the Python wrappers generated by SWIG will not release the
+    Python's interpreter's Global Interpreter Lock (GIL) when wrapped C/C++ code is
+entered.  Hence, while any of the wrapped C/C++ code is executing, the Python interpreter
+will not be able to run any other threads, even if the wrapped C/C++ code is waiting
+    in a blocking call for something like network or disk IO.
+
+    Fortunately, SWIG does have the ability to enable multithreaded support and automatic
+    release of the GIL either for all wrapped code  in a module or on a more selective basis.  The user
+    interface for this is described in the next section.
+</p>
+
+<H3><a name="Python_thread_UI">36.13.1 UI for Enabling Multithreading Support</a></H3>
+
+
+<p>The user interface is as follows:</p>
+<ol>
+  <li><p>Module thread support can be enabled in two ways:</p>
+    <ul>
+      <li>
+        <p>
+        The <tt>-threads</tt> swig python option at the command line (or in <tt>setup.py</tt>):
+        </p>
+        <div class="shell"><pre>$ swig -python -threads example.i</pre></div>
+      </li>
+      <li>
+        <p>
+        The <tt>threads</tt> module option in the *.i template file:
+        </p>
+        <div class="code"><pre>%feature("nothread") method;</pre></div>
+      </li>
+    </ul>
+  </li>
+  <li><p>You can disable thread support for a given method:</p>
+    <div class="code"><pre>%module("threads"=1)</pre></div>
+      or
+      <div class="code"><pre>%nothread method;</pre></div>
+  </li>
+  <li><p>You can partially disable thread support for a given method:</p>
+    <ul>
+      <li><p>To disable the C++/python thread protection:</p>
+        <div class="code"><pre>%feature("nothreadblock") method;</pre></div>
+          or
+          <div class="code"><pre>%nothreadblock method;</pre></div>
+      </li>
+      <li>
+        <p>To disable the python/C++ thread protection</p>
+        <div class="code"><pre>%feature("nothreadallow") method;</pre></div>
+          or
+          <div class="code"><pre>%nothreadallow method;</pre></div>
+      </li>
+    </ul>
+  </li>
+</ol>
+
+<H3><a name="Python_thread_performance">36.13.2 Multithread Performance</a></H3>
+
+
+<p>
+    For the curious about performance, here are some numbers for the profiletest.i test,
+    which is used to check the speed of the wrapped code:
+</p>
+
+<table summary="Python multithread performance">
+    <tr>
+        <th>Thread Mode</th>
+        <th>Execution Time (sec)</th>
+        <th>Comment</th>
+    </tr>
+    <tr>
+        <td>Single Threaded</td>
+        <td>9.6</td>
+        <td>no "-threads" option given</td>
+    </tr>
+    <tr>
+        <td>Fully Multithreaded</td>
+        <td>15.5</td>
+        <td>"-threads" option = 'allow' + 'block'</td>
+    </tr>
+    <tr>
+        <td>No Thread block</td>
+        <td>12.2</td>
+        <td>only 'allow'</td>
+    </tr>
+    <tr>
+        <td>No Thread Allow</td>
+        <td>13.6</td>
+        <td>only block'</td>
+    </tr>
+</table>
+
+<p>
+    Fullly threaded code decreases the wrapping performance by
+    around 60%. If that is important to your application, you
+    can tune each method using the different 'nothread',
+    'nothreadblock' or 'nothreadallow' features as
+    needed. Note that for some methods deactivating the
+    'thread block' or 'thread allow' code is not an option,
+    so, be careful.
+</p>
+
 </body>
 </html>