12 files changed, 178 insertions, 53 deletions
diff --git a/docs/examples/userguide/parallelism/breaking_loop.py b/docs/examples/userguide/parallelism/breaking_loop.py
new file mode 100644
index 000000000..00d0225b5
--- /dev/null
+++ b/docs/examples/userguide/parallelism/breaking_loop.py
@@ -0,0 +1,15 @@
+from cython.parallel import prange
+
+@cython.exceptval(-1)
+@cython.cfunc
+def func(n: cython.Py_ssize_t) -> cython.int:
+    i: cython.Py_ssize_t
+
+    for i in prange(n, nogil=True):
+        if i == 8:
+            with cython.gil:
+                raise Exception()
+        elif i == 4:
+            break
+        elif i == 2:
+            return i
diff --git a/docs/examples/userguide/parallelism/breaking_loop.pyx b/docs/examples/userguide/parallelism/breaking_loop.pyx
index d11b179d9..e7445082d 100644
--- a/docs/examples/userguide/parallelism/breaking_loop.pyx
+++ b/docs/examples/userguide/parallelism/breaking_loop.pyx
@@ -1,13 +1,15 @@
-from cython.parallel import prange
-
-cdef int func(Py_ssize_t n):
-    cdef Py_ssize_t i
-
-    for i in prange(n, nogil=True):
-        if i == 8:
-            with gil:
-                raise Exception()
-        elif i == 4:
-            break
-        elif i == 2:
-            return i
+from cython.parallel import prange
+
+
+
+cdef int func(Py_ssize_t n) except -1:
+    cdef Py_ssize_t i
+
+    for i in prange(n, nogil=True):
+        if i == 8:
+            with gil:
+                raise Exception()
+        elif i == 4:
+            break
+        elif i == 2:
+            return i
diff --git a/docs/examples/userguide/parallelism/cimport_openmp.py b/docs/examples/userguide/parallelism/cimport_openmp.py
new file mode 100644
index 000000000..9288a4381
--- /dev/null
+++ b/docs/examples/userguide/parallelism/cimport_openmp.py
@@ -0,0 +1,11 @@
+# tag: openmp
+
+from cython.parallel import parallel
+from cython.cimports.openmp import omp_set_dynamic, omp_get_num_threads
+
+num_threads = cython.declare(cython.int)
+
+omp_set_dynamic(1)
+with cython.nogil, parallel():
+    num_threads = omp_get_num_threads()
+    # ...
diff --git a/docs/examples/userguide/parallelism/cimport_openmp.pyx b/docs/examples/userguide/parallelism/cimport_openmp.pyx
index 235ee10bc..54d5f18db 100644
--- a/docs/examples/userguide/parallelism/cimport_openmp.pyx
+++ b/docs/examples/userguide/parallelism/cimport_openmp.pyx
@@ -1,13 +1,11 @@
-# tag: openmp
-# You can ignore the previous line.
-# It's for internal testing of the Cython documentation.
-
-from cython.parallel cimport parallel
-cimport openmp
-
-cdef int num_threads
-
-openmp.omp_set_dynamic(1)
-with nogil, parallel():
-    num_threads = openmp.omp_get_num_threads()
-    # ...
+# tag: openmp
+
+from cython.parallel cimport parallel
+cimport openmp
+
+cdef int num_threads
+
+openmp.omp_set_dynamic(1)
+with nogil, parallel():
+    num_threads = openmp.omp_get_num_threads()
+    # ...
diff --git a/docs/examples/userguide/parallelism/memoryview_sum.py b/docs/examples/userguide/parallelism/memoryview_sum.py
new file mode 100644
index 000000000..6cff5d587
--- /dev/null
+++ b/docs/examples/userguide/parallelism/memoryview_sum.py
@@ -0,0 +1,7 @@
+from cython.parallel import prange
+
+def func(x: cython.double[:], alpha: cython.double):
+    i: cython.Py_ssize_t
+
+    for i in prange(x.shape[0], nogil=True):
+        x[i] = alpha * x[i]
diff --git a/docs/examples/userguide/parallelism/memoryview_sum.pyx b/docs/examples/userguide/parallelism/memoryview_sum.pyx
new file mode 100644
index 000000000..bdc1c9feb
--- /dev/null
+++ b/docs/examples/userguide/parallelism/memoryview_sum.pyx
@@ -0,0 +1,7 @@
+from cython.parallel import prange
+
+def func(double[:] x, double alpha):
+    cdef Py_ssize_t i
+
+    for i in prange(x.shape[0], nogil=True):
+        x[i] = alpha * x[i]
diff --git a/docs/examples/userguide/parallelism/parallel.py b/docs/examples/userguide/parallelism/parallel.py
new file mode 100644
index 000000000..0fb62d10f
--- /dev/null
+++ b/docs/examples/userguide/parallelism/parallel.py
@@ -0,0 +1,30 @@
+from cython.parallel import parallel, prange
+from cython.cimports.libc.stdlib import abort, malloc, free
+
+@cython.nogil
+@cython.cfunc
+def func(buf: cython.p_int) -> cython.void:
+    pass
+    # ...
+
+idx = cython.declare(cython.Py_ssize_t)
+i = cython.declare(cython.Py_ssize_t)
+j = cython.declare(cython.Py_ssize_t)
+n = cython.declare(cython.Py_ssize_t, 100)
+local_buf = cython.declare(p_int)
+size = cython.declare(cython.size_t, 10)
+
+with cython.nogil, parallel():
+    local_buf: cython.p_int = cython.cast(cython.p_int, malloc(cython.sizeof(cython.int) * size))
+    if local_buf is cython.NULL:
+        abort()
+
+    # populate our local buffer in a sequential loop
+    for i in range(size):
+        local_buf[i] = i * 2
+
+    # share the work using the thread-local buffer(s)
+    for j in prange(n, schedule='guided'):
+        func(local_buf)
+
+    free(local_buf)
diff --git a/docs/examples/userguide/parallelism/parallel.pyx b/docs/examples/userguide/parallelism/parallel.pyx
new file mode 100644
index 000000000..2a952d537
--- /dev/null
+++ b/docs/examples/userguide/parallelism/parallel.pyx
@@ -0,0 +1,30 @@
+from cython.parallel import parallel, prange
+from libc.stdlib cimport abort, malloc, free
+
+
+
+cdef void func(int *buf) nogil:
+    pass
+    # ...
+
+cdef Py_ssize_t idx, i, j, n = 100
+cdef int * local_buf
+cdef size_t size = 10
+
+
+
+
+with nogil, parallel():
+    local_buf = <int *> malloc(sizeof(int) * size)
+    if local_buf is NULL:
+        abort()
+
+    # populate our local buffer in a sequential loop
+    for i in range(size):
+        local_buf[i] = i * 2
+
+    # share the work using the thread-local buffer(s)
+    for j in prange(n, schedule='guided'):
+        func(local_buf)
+
+    free(local_buf)
diff --git a/docs/examples/userguide/parallelism/setup_py.py b/docs/examples/userguide/parallelism/setup_py.py
new file mode 100644
index 000000000..85a037dc5
--- /dev/null
+++ b/docs/examples/userguide/parallelism/setup_py.py
@@ -0,0 +1,16 @@
+from setuptools import Extension, setup
+from Cython.Build import cythonize
+
+ext_modules = [
+    Extension(
+        "hello",
+        ["hello.py"],
+        extra_compile_args=['-fopenmp'],
+        extra_link_args=['-fopenmp'],
+    )
+]
+
+setup(
+    name='hello-parallel-world',
+    ext_modules=cythonize(ext_modules),
+)
diff --git a/docs/examples/userguide/parallelism/setup.py b/docs/examples/userguide/parallelism/setup_pyx.py
index 0fb6026f7..fe6d0a64c 100644
--- a/docs/examples/userguide/parallelism/setup.py
+++ b/docs/examples/userguide/parallelism/setup_pyx.py
@@ -1,17 +1,16 @@
-from distutils.core import setup
-from distutils.extension import Extension
-from Cython.Build import cythonize
-
-ext_modules = [
-    Extension(
-        "hello",
-        ["hello.pyx"],
-        extra_compile_args=['-fopenmp'],
-        extra_link_args=['-fopenmp'],
-    )
-]
-
-setup(
-    name='hello-parallel-world',
-    ext_modules=cythonize(ext_modules),
-)
+from setuptools import Extension, setup
+from Cython.Build import cythonize
+
+ext_modules = [
+    Extension(
+        "hello",
+        ["hello.pyx"],
+        extra_compile_args=['-fopenmp'],
+        extra_link_args=['-fopenmp'],
+    )
+]
+
+setup(
+    name='hello-parallel-world',
+    ext_modules=cythonize(ext_modules),
+)
diff --git a/docs/examples/userguide/parallelism/simple_sum.py b/docs/examples/userguide/parallelism/simple_sum.py
new file mode 100644
index 000000000..f952a8556
--- /dev/null
+++ b/docs/examples/userguide/parallelism/simple_sum.py
@@ -0,0 +1,10 @@
+from cython.parallel import prange
+
+i = cython.declare(cython.int)
+n = cython.declare(cython.int, 30)
+sum = cython.declare(cython.int, 0)
+
+for i in prange(n, nogil=True):
+    sum += i
+
+print(sum)
diff --git a/docs/examples/userguide/parallelism/simple_sum.pyx b/docs/examples/userguide/parallelism/simple_sum.pyx
index 83b862ea6..929a988e5 100644
--- a/docs/examples/userguide/parallelism/simple_sum.pyx
+++ b/docs/examples/userguide/parallelism/simple_sum.pyx
@@ -1,10 +1,10 @@
-from cython.parallel import prange
-
-cdef int i
-cdef int n = 30
-cdef int sum = 0
-
-for i in prange(n, nogil=True):
-    sum += i
-
-print(sum)
+from cython.parallel import prange
+
+cdef int i
+cdef int n = 30
+cdef int sum = 0
+
+for i in prange(n, nogil=True):
+    sum += i
+
+print(sum)