Merged revisions 87792 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r87792 | antoine.pitrou | 2011-01-06 17:31:28 +0100 (jeu., 06 janv. 2011) | 3 lines

  Elaborate about the GIL.
........

1 files changed, 11 insertions, 0 deletions

diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 142f1ec..4a6041f 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -26,11 +26,22 @@ The :mod:`dummy_threading` module is provided for situations where
    Starting with Python 2.5, several Thread methods raise :exc:`RuntimeError`
    instead of :exc:`AssertionError` if called erroneously.
 
+.. impl-detail::
+
+   Due to the :term:`Global Interpreter Lock`, in CPython only one thread
+   can execute Python code at once (even though certain performance-oriented
+   libraries might overcome this limitation).
+   If you want your application to make better of use of the computational
+   resources of multi-core machines, you are advised to use
+   :mod:`multiprocessing`. However, threading is still an appropriate model
+   if you want to run multiple I/O-bound tasks simultaneously.
+
 .. seealso::
 
    Latest version of the `threading module Python source code
    <http://svn.python.org/view/python/branches/release27-maint/Lib/threading.py?view=markup>`_
 
+
 This module defines the following functions and objects:
 
 .. function:: active_count()