Add a couple of words about the new GIL implementation

2 files changed, 46 insertions, 0 deletions

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 82e978e..5d1a7c0 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -282,6 +282,9 @@ always available.
 
    Return the interpreter's "check interval"; see :func:`setcheckinterval`.
 
+   .. deprecated:: 3.2
+      Use :func:`getswitchinterval` instead.
+
 
 .. function:: getdefaultencoding()
 
@@ -345,6 +348,12 @@ always available.
    collector.
 
 
+.. function:: getswitchinterval()
+
+   Return the interpreter's "thread switch interval"; see
+   :func:`setswitchinterval`.
+
+
 .. function:: _getframe([depth])
 
    Return a frame object from the call stack.  If optional integer *depth* is
@@ -626,6 +635,11 @@ always available.
    performance for programs using threads.  Setting it to a value ``<=`` 0 checks
    every virtual instruction, maximizing responsiveness as well as overhead.
 
+   .. deprecated:: 3.2
+      This function doesn't have an effect anymore, as the internal logic
+      for thread switching and asynchronous tasks has been rewritten.
+      Use :func:`setswitchinterval` instead.
+
 
 .. function:: setdefaultencoding(name)
 
@@ -689,6 +703,17 @@ always available.
    limit can lead to a crash.
 
 
+.. function:: setswitchinterval(interval)
+
+   Set the interpreter's thread switch interval (in seconds).  This floating-point
+   value determines the ideal duration of the "timeslices" allocated to
+   concurrently running Python threads.  Please note that the actual value
+   can be higher, especially if long-running internal functions or methods
+   are used.  Also, which thread becomes scheduled at the end of the interval
+   is the operating system's decision.  The interpreter doesn't have its
+   own scheduler.
+
+
 .. function:: settrace(tracefunc)
 
    .. index::
diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst
index 945e4b3..a47ee99 100644
--- a/Doc/whatsnew/3.2.rst
+++ b/Doc/whatsnew/3.2.rst
@@ -85,6 +85,27 @@ New, Improved, and Deprecated Modules
   (Contributed by Georg Brandl and Mattias Brändström;
   `appspot issue 53094 <http://codereview.appspot.com/53094>`_.)
 
+Multi-threading
+===============
+
+* The mechanism for serializing execution of concurrently running Python
+  threads (generally known as the GIL or Global Interpreter Lock) has been
+  rewritten.  Among the objectives were more predictable switching intervals
+  and reduced overhead due to lock contention and the number of ensuing
+  system calls.  The notion of a "check interval" to allow thread switches
+  has been abandoned and replaced by an absolute duration expressed in
+  seconds.  This parameter is tunable through :func:`sys.setswitchinterval()`.
+  It currently defaults to 5 milliseconds.
+
+  Additional details about the implementation can be read from a `python-dev
+  mailing-list message
+  <http://mail.python.org/pipermail/python-dev/2009-October/093321.html>`_
+  (however, "priority requests" as exposed in this message have not been
+  kept for inclusion).
+
+  (Contributed by Antoine Pitrou)
+
+
 Optimizations
 =============