Elaborate about the GIL.
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 371ac90..74c9976 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -17,11 +17,23 @@
methods and functions in this module in the Python 2.x series are still
supported by this module.
+.. 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` or :class:`concurrent.futures.ProcessPoolExecutor`.
+ However, threading is still an appropriate model if you want to run
+ multiple I/O-bound tasks simultaneously.
+
.. seealso::
Latest version of the :source:`threading module Python source code
<Lib/threading.py>`
+
This module defines the following functions and objects: