summaryrefslogtreecommitdiffstats
path: root/Doc/c-api/init.rst
diff options
context:
space:
mode:
authorAntoine Pitrou <solipsis@pitrou.net>2013-09-30 19:38:49 (GMT)
committerAntoine Pitrou <solipsis@pitrou.net>2013-09-30 19:38:49 (GMT)
commitc8fb4fc96e350ac47881c508556d435bb7605687 (patch)
tree646b07d50046e5d1f9090fba1aba5ac0bcdc8be6 /Doc/c-api/init.rst
parent63f03ed3dbbf542866a715bc92c652fba26ac26e (diff)
parent1a67bee7016ab266b8a19a8834a2f1cb374dc38c (diff)
downloadcpython-c8fb4fc96e350ac47881c508556d435bb7605687.zip
cpython-c8fb4fc96e350ac47881c508556d435bb7605687.tar.gz
cpython-c8fb4fc96e350ac47881c508556d435bb7605687.tar.bz2
Add a "skull and crossbones" to Py_AddPendingCall.
Diffstat (limited to 'Doc/c-api/init.rst')
-rw-r--r--Doc/c-api/init.rst55
1 files changed, 30 insertions, 25 deletions
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 32007d5..9ed2a3a 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -446,6 +446,9 @@ pointer.
standard :mod:`zlib` and :mod:`hashlib` modules release the GIL when
compressing or hashing data.
+
+.. _gilstate:
+
Non-Python created threads
--------------------------
@@ -923,41 +926,43 @@ Asynchronous Notifications
A mechanism is provided to make asynchronous notifications to the main
interpreter thread. These notifications take the form of a function
-pointer and a void argument.
+pointer and a void pointer argument.
-.. index:: single: setcheckinterval() (in module sys)
-
-Every check interval, when the global interpreter lock is released and
-reacquired, Python will also call any such provided functions. This can be used
-for example by asynchronous IO handlers. The notification can be scheduled from
-a worker thread and the actual call than made at the earliest convenience by the
-main thread where it has possession of the global interpreter lock and can
-perform any Python API calls.
.. c:function:: int Py_AddPendingCall(int (*func)(void *), void *arg)
.. index:: single: Py_AddPendingCall()
- Post a notification to the Python main thread. If successful, *func* will be
- called with the argument *arg* at the earliest convenience. *func* will be
- called having the global interpreter lock held and can thus use the full
- Python API and can take any action such as setting object attributes to
- signal IO completion. It must return 0 on success, or -1 signalling an
- exception. The notification function won't be interrupted to perform another
- asynchronous notification recursively, but it can still be interrupted to
- switch threads if the global interpreter lock is released, for example, if it
- calls back into Python code.
+ Schedule a function to be called from the main interpreter thread. On
+ success, 0 is returned and *func* is queued for being called in the
+ main thread. On failure, -1 is returned without setting any exception.
- This function returns 0 on success in which case the notification has been
- scheduled. Otherwise, for example if the notification buffer is full, it
- returns -1 without setting any exception.
+ When successfully queued, *func* will be *eventually* called from the
+ main interpreter thread with the argument *arg*. It will be called
+ asynchronously with respect to normally running Python code, but with
+ both these conditions met:
- This function can be called on any thread, be it a Python thread or some
- other system thread. If it is a Python thread, it doesn't matter if it holds
- the global interpreter lock or not.
+ * on a :term:`bytecode` boundary;
+ * with the main thread holding the :term:`global interpreter lock`
+ (*func* can therefore use the full C API).
- .. versionadded:: 3.1
+ *func* must return 0 on success, or -1 on failure with an exception
+ set. *func* won't be interrupted to perform another asynchronous
+ notification recursively, but it can still be interrupted to switch
+ threads if the global interpreter lock is released.
+ This function doesn't need a current thread state to run, and it doesn't
+ need the global interpreter lock.
+
+ .. warning::
+ This is a low-level function, only useful for very special cases.
+ There is no guarantee that *func* will be called as quick as
+ possible. If the main thread is busy executing a system call,
+ *func* won't be called before the system call returns. This
+ function is generally **not** suitable for calling Python code from
+ arbitrary C threads. Instead, use the :ref:`PyGILState API<gilstate>`.
+
+ .. versionadded:: 3.1
.. _profiling: