Followup to bug #1069160.
PyThreadState_SetAsyncExc(): internal correctness changes wrt
refcount safety and deadlock avoidance. Also added a basic test
case (relying on ctypes) and repaired the docs.
diff --git a/Doc/api/init.tex b/Doc/api/init.tex
index 9225f69..e380bdb 100644
--- a/Doc/api/init.tex
+++ b/Doc/api/init.tex
@@ -696,15 +696,15 @@
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyThreadState_SetAsyncExc}{long id, PyObject *exc}
- Asynchronously raise an exception in a thread.
+ Asynchronously raise an exception in a thread.
The \var{id} argument is the thread id of the target thread;
\var{exc} is the exception object to be raised.
This function does not steal any references to \var{exc}.
- To prevent naive misuse, you must write your own C extension
- to call this. Must be called with the GIL held.
- Returns the number of thread states modified; if it returns a number
- greater than one, you're in trouble, and you should call it again
- with \var{exc} set to \constant{NULL} to revert the effect.
+ To prevent naive misuse, you must write your own C extension
+ to call this. Must be called with the GIL held.
+ Returns the number of thread states modified; this is normally one, but
+ will be zero if the thread id isn't found. If \var{exc} is
+ \constant{NULL}, the pending exception (if any) for the thread is cleared.
This raises no exceptions.
\versionadded{2.3}
\end{cfuncdesc}