diff --git a/docs/src/userguide/external_C_code.rst b/docs/src/userguide/external_C_code.rst index 38600863a19dae7fd335b7f77310fbd10200f90c..f9a50f6a65bde6102e9b4f960da02909f761419f 100644 --- a/docs/src/userguide/external_C_code.rst +++ b/docs/src/userguide/external_C_code.rst @@ -446,6 +446,14 @@ header:: cdef void my_callback(void *data) with gil: ... +If the callback may be called from another thread then the main thread which may not be a Python thread, +care must be taken to initialize the GIL first, through a call to ``PyEval_InitThreads()``. + +The GIL may also be acquired through the ``with nogil`` counterpart ``with gil``:: + + with gil: + <execute this block with the GIL acquired> + Declaring a function as callable without the GIL -------------------------------------------------- diff --git a/docs/src/userguide/parallelism.rst b/docs/src/userguide/parallelism.rst index 6808b57e97a4c40022b25636f92d4e3b95e1518c..68eb10a6411b093f44985c1ff246809b6bcf8825 100644 --- a/docs/src/userguide/parallelism.rst +++ b/docs/src/userguide/parallelism.rst @@ -11,6 +11,8 @@ module. To use this kind of parallelism, the GIL must be released (see :ref:`Releasing the GIL <nogil>`). It currently supports OpenMP, but later on more backends might be supported. +.. NOTE:: Because the backend is OpenMP, cython.parallel functionality may only be used from the main thread or from OpenMP threads. + __ nogil_ .. function:: prange([start,] stop[, step], nogil=False, schedule=None) @@ -76,11 +78,11 @@ __ nogil_ print sum - Example with a shared numpy array:: + Example with a typed memoryview (e.g. a NumPy array):: from cython.parallel import prange - def func(np.ndarray[double] x, double alpha): + def func(double[:] x, double alpha): cdef Py_ssize_t i for i in prange(x.shape[0]): @@ -152,7 +154,7 @@ enable OpenMP. For gcc this can be done as follows in a setup.py:: Breaking ======== The parallel with and prange blocks support break, continue and return in -nogil mode. Additionally, it is valid to use a with gil block inside these +nogil mode. Additionally, it is valid to use a ``with gil`` block inside these blocks, and have exceptions propagate from them. However, because the blocks use OpenMP, they can not just be left, so the exiting procedure is best-effort. For prange() this means that the loop