Issue #10913: Deprecate misleading functions PyEval_AcquireLock() and

PyEval_ReleaseLock().  The thread-state aware APIs should be used instead.

diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index f920909e6499505e7d274f9905809432cb2568ff..fd1f7d0a7ccb4254e2f26226d53947fbdb4d8f08 100644 (file)
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -759,6 +759,10 @@ been created.
    *tstate*, which should not be *NULL*.  The lock must have been created earlier.
    If this thread already has the lock, deadlock ensues.
 
+   :c:func:`PyEval_RestoreThread` is a higher-level function which is always
+   available (even when thread support isn't enabled or when threads have
+   not been initialized).
+
 
 .. c:function:: void PyEval_ReleaseThread(PyThreadState *tstate)
 
@@ -768,17 +772,31 @@ been created.
    that it represents the current thread state --- if it isn't, a fatal error is
    reported.
 
+   :c:func:`PyEval_SaveThread` is a higher-level function which is always
+   available (even when thread support isn't enabled or when threads have
+   not been initialized).
+
 
 .. c:function:: void PyEval_AcquireLock()
 
    Acquire the global interpreter lock.  The lock must have been created earlier.
    If this thread already has the lock, a deadlock ensues.
 
+   .. deprecated:: 3.2
+      This function does not change the current thread state.  Please use
+      :c:func:`PyEval_RestoreThread` or :c:func:`PyEval_AcquireThread`
+      instead.
+
 
 .. c:function:: void PyEval_ReleaseLock()
 
    Release the global interpreter lock.  The lock must have been created earlier.
 
+   .. deprecated:: 3.2
+      This function does not change the current thread state.  Please use
+      :c:func:`PyEval_SaveThread` or :c:func:`PyEval_ReleaseThread`
+      instead.
+
 
 Sub-interpreter support
 =======================

diff --git a/Misc/NEWS b/Misc/NEWS
index 24264dc472422eb5c8f0d93f42d3867dc967bc35..68aae79c9bfef9da1c59b24f0335094645d425c4 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -200,6 +200,9 @@ Library
 C-API
 -----
 
+- Issue #10913: Deprecate misleading functions PyEval_AcquireLock() and
+  PyEval_ReleaseLock().  The thread-state aware APIs should be used instead.
+
 - Issue #10333: Remove ancient GC API, which has been deprecated since
   Python 2.2.