CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 311 – Simplified Global Interpreter Lock Acquisition for Extensions | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0311/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 311 – Simplified Global Interpreter Lock Acquisition for Extensions | peps.python.org'> <meta property="og:description" content="This PEP proposes a simplified API for access to the Global Interpreter Lock (GIL) for Python extension modules. Specifically, it provides a solution for authors of complex multi-threaded extensions, where the current state of Python (i.e., the state of..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0311/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="This PEP proposes a simplified API for access to the Global Interpreter Lock (GIL) for Python extension modules. Specifically, it provides a solution for authors of complex multi-threaded extensions, where the current state of Python (i.e., the state of..."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 311</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 311 – Simplified Global Interpreter Lock Acquisition for Extensions</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Mark Hammond <mhammond at skippinet.com.au></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Created:</dt> <dd class="field-even">05-Feb-2003</dd> <dt class="field-odd">Python-Version:</dt> <dd class="field-odd">2.3</dd> <dt class="field-even">Post-History:</dt> <dd class="field-even">05-Feb-2003, 14-Feb-2003, 19-Apr-2003</dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#limitations-and-exclusions">Limitations and Exclusions</a></li> <li><a class="reference internal" href="#proposal">Proposal</a></li> <li><a class="reference internal" href="#design-and-implementation">Design and Implementation</a></li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> This PEP proposes a simplified API for access to the Global Interpreter Lock (GIL) for Python extension modules. Specifically, it provides a solution for authors of complex multi-threaded extensions, where the current state of Python (i.e., the state of the GIL is unknown. This PEP proposes a new API, for platforms built with threading support, to manage the Python thread state. An implementation strategy is proposed, along with an initial, platform independent implementation. </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> The current Python interpreter state API is suitable for simple, single-threaded extensions, but quickly becomes incredibly complex for non-trivial, multi-threaded extensions. Currently Python provides two mechanisms for dealing with the GIL: <ul class="simple"> <li><code class="docutils literal notranslate">Py_BEGIN_ALLOW_THREADS</code> and <code class="docutils literal notranslate">Py_END_ALLOW_THREADS</code> macros. These macros are provided primarily to allow a simple Python extension that already owns the GIL to temporarily release it while making an “external” (ie, non-Python), generally expensive, call. Any existing Python threads that are blocked waiting for the GIL are then free to run. While this is fine for extensions making calls from Python into the outside world, it is no help for extensions that need to make calls into Python when the thread state is unknown.</li> <li><code class="docutils literal notranslate">PyThreadState</code> and <code class="docutils literal notranslate">PyInterpreterState</code> APIs. These API functions allow an extension/embedded application to acquire the GIL, but suffer from a serious boot-strapping problem - they require you to know the state of the Python interpreter and of the GIL before they can be used. One particular problem is for extension authors that need to deal with threads never before seen by Python, but need to call Python from this thread. It is very difficult, delicate and error prone to author an extension where these “new” threads always know the exact state of the GIL, and therefore can reliably interact with this API.</li> </ul> For these reasons, the question of how such extensions should interact with Python is quickly becoming a FAQ. The main impetus for this PEP, a thread on python-dev <a class="footnote-reference brackets" href="#id2" id="id1">[1]</a>, immediately identified the following projects with this exact issue: <ul class="simple"> <li>The win32all extensions</li> <li>Boost</li> <li>ctypes</li> <li>Python-GTK bindings</li> <li>Uno</li> <li>PyObjC</li> <li>Mac toolbox</li> <li>PyXPCOM</li> </ul> Currently, there is no reasonable, portable solution to this problem, forcing each extension author to implement their own hand-rolled version. Further, the problem is complex, meaning many implementations are likely to be incorrect, leading to a variety of problems that will often manifest simply as “Python has hung”. While the biggest problem in the existing thread-state API is the lack of the ability to query the current state of the lock, it is felt that a more complete, simplified solution should be offered to extension authors. Such a solution should encourage authors to provide error-free, complex extension modules that take full advantage of Python’s threading mechanisms. </section> <section id="limitations-and-exclusions"> <h2><a class="toc-backref" href="#limitations-and-exclusions" role="doc-backlink">Limitations and Exclusions</a></h2> This proposal identifies a solution for extension authors with complex multi-threaded requirements, but that only require a single “PyInterpreterState”. There is no attempt to cater for extensions that require multiple interpreter states. At the time of writing, no extension has been identified that requires multiple PyInterpreterStates, and indeed it is not clear if that facility works correctly in Python itself. This API will not perform automatic initialization of Python, or initialize Python for multi-threaded operation. Extension authors must continue to call <code class="docutils literal notranslate">Py_Initialize()</code>, and for multi-threaded applications, <code class="docutils literal notranslate">PyEval_InitThreads()</code>. The reason for this is that the first thread to call <code class="docutils literal notranslate">PyEval_InitThreads()</code> is nominated as the “main thread” by Python, and so forcing the extension author to specify the main thread (by requiring them to make this first call) removes ambiguity. As <code class="docutils literal notranslate">Py_Initialize()</code> must be called before <code class="docutils literal notranslate">PyEval_InitThreads()</code>, and as both of these functions currently support being called multiple times, the burden this places on extension authors is considered reasonable. It is intended that this API be all that is necessary to acquire the Python GIL. Apart from the existing, standard <code class="docutils literal notranslate">Py_BEGIN_ALLOW_THREADS</code> and <code class="docutils literal notranslate">Py_END_ALLOW_THREADS</code> macros, it is assumed that no additional thread state API functions will be used by the extension. Extensions with such complicated requirements are free to continue to use the existing thread state API. </section> <section id="proposal"> <h2><a class="toc-backref" href="#proposal" role="doc-backlink">Proposal</a></h2> This proposal recommends a new API be added to Python to simplify the management of the GIL. This API will be available on all platforms built with <code class="docutils literal notranslate">WITH_THREAD</code> defined. The intent is that assuming Python has correctly been initialized, an extension author be able to use a small, well-defined “prologue dance”, at any time and on any thread, which will ensure Python is ready to be used on that thread. After the extension has finished with Python, it must also perform an “epilogue dance” to release any resources previously acquired. Ideally, these dances can be expressed in a single line. Specifically, the following new APIs are proposed: <div class="highlight-default notranslate"><div class="highlight"><pre>/* Ensure that the current thread is ready to call the Python C API, regardless of the current state of Python, or of its thread lock. This may be called as many times as desired by a thread so long as each call is matched with a call to PyGILState_Release(). In general, other thread-state APIs may be used between _Ensure() and _Release() calls, so long as the thread-state is restored to its previous state before the Release(). For example, normal use of the Py_BEGIN_ALLOW_THREADS/ Py_END_ALLOW_THREADS macros are acceptable. The return value is an opaque "handle" to the thread state when PyGILState_Acquire() was called, and must be passed to PyGILState_Release() to ensure Python is left in the same state. Even though recursive calls are allowed, these handles can *not* be shared - each unique call to PyGILState_Ensure must save the handle for its call to PyGILState_Release. When the function returns, the current thread will hold the GIL. Failure is a fatal error. */ PyAPI_FUNC(PyGILState_STATE) PyGILState_Ensure(void); /* Release any resources previously acquired. After this call, Python's state will be the same as it was prior to the corresponding PyGILState_Acquire call (but generally this state will be unknown to the caller, hence the use of the GILState API.) Every call to PyGILState_Ensure must be matched by a call to PyGILState_Release on the same thread. */ PyAPI_FUNC(void) PyGILState_Release(PyGILState_STATE); </pre></div> </div> Common usage will be: <div class="highlight-default notranslate"><div class="highlight"><pre>void SomeCFunction(void) { /* ensure we hold the lock */ PyGILState_STATE state = PyGILState_Ensure(); /* Use the Python API */ ... /* Restore the state of Python */ PyGILState_Release(state); } </pre></div> </div> </section> <section id="design-and-implementation"> <h2><a class="toc-backref" href="#design-and-implementation" role="doc-backlink">Design and Implementation</a></h2> The general operation of <code class="docutils literal notranslate">PyGILState_Ensure()</code> will be: <ul class="simple"> <li>assert Python is initialized.</li> <li>Get a <code class="docutils literal notranslate">PyThreadState</code> for the current thread, creating and saving if necessary.</li> <li>remember the current state of the lock (owned/not owned)</li> <li>If the current state does not own the GIL, acquire it.</li> <li>Increment a counter for how many calls to <code class="docutils literal notranslate">PyGILState_Ensure</code> have been made on the current thread.</li> <li>return</li> </ul> The general operation of <code class="docutils literal notranslate">PyGILState_Release()</code> will be: <ul class="simple"> <li>assert our thread currently holds the lock.</li> <li>If old state indicates lock was previously unlocked, release GIL.</li> <li>Decrement the <code class="docutils literal notranslate">PyGILState_Ensure</code> counter for the thread.</li> <li>If counter == 0:<ul> <li>release and delete the <code class="docutils literal notranslate">PyThreadState</code>.</li> <li>forget the <code class="docutils literal notranslate">ThreadState</code> as being owned by the thread.</li> </ul> </li> <li>return</li> </ul> It is assumed that it is an error if two discrete <code class="docutils literal notranslate">PyThreadStates</code> are used for a single thread. Comments in <code class="docutils literal notranslate">pystate.h</code> (“State unique per thread”) support this view, although it is never directly stated. Thus, this will require some implementation of Thread Local Storage. Fortunately, a platform independent implementation of Thread Local Storage already exists in the Python source tree, in the SGI threading port. This code will be integrated into the platform independent Python core, but in such a way that platforms can provide a more optimal implementation if desired. </section> <section id="implementation"> <h2><a class="toc-backref" href="#implementation" role="doc-backlink">Implementation</a></h2> An implementation of this proposal can be found at <a class="reference external" href="https://bugs.python.org/issue684256">https://bugs.python.org/issue684256</a> </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id2" role="doc-footnote"> <dt class="label" id="id2">[<a href="#id1">1</a>]</dt> <dd>David Abrahams, Extension modules, Threading, and the GIL <a class="reference external" href="https://mail.python.org/pipermail/python-dev/2002-December/031424.html">https://mail.python.org/pipermail/python-dev/2002-December/031424.html</a></aside> </aside> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed in the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0311.rst">https://github.com/python/peps/blob/main/peps/pep-0311.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0311.rst">2025-02-01 08:59:27 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#limitations-and-exclusions">Limitations and Exclusions</a></li> <li><a class="reference internal" href="#proposal">Proposal</a></li> <li><a class="reference internal" href="#design-and-implementation">Design and Implementation</a></li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0311.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>