Merge pull request #2390 from gabrieldemarmiesse/rendering_parameters

Changed the organisation of prange.

docs/src/userguide/parallelism.rst

@@ -21,9 +21,7 @@ It currently supports OpenMP, but later on more backends might be supported.
 
     This function can be used for parallel loops. OpenMP automatically
     starts a thread pool and distributes the work according to the schedule
-    used. ``step`` must not be 0. This function can only be used with the
-    GIL released. If ``nogil`` is true, the loop will be wrapped in a nogil
-    section.
+    used.
 
     Thread-locality and reductions are automatically inferred for variables.
 
@@ -36,80 +34,99 @@ It currently supports OpenMP, but later on more backends might be supported.
     Variables assigned to in a parallel with block will be private and unusable
     after the block, as there is no concept of a sequentially last value.
 
-    The ``schedule`` is passed to OpenMP and can be one of the following:
 
-    static:
-       If a chunksize is provided, iterations are distributed to all
-       threads ahead of time in blocks of the given chunksize.  If no
-       chunksize is given, the iteration space is divided into chunks that
-       are approximately equal in size, and at most one chunk is assigned
-       to each thread in advance.
+    :param start:
+        The index indicating the start of the loop (same as the start argument in range).
 
-       This is most appropriate when the scheduling overhead matters and
-       the problem can be cut down into equally sized chunks that are
-       known to have approximately the same runtime.
+    :param stop:
+        The index indicating when to stop the loop (same as the stop argument in range).
 
-    dynamic:
-       The iterations are distributed to threads as they request them,
-       with a default chunk size of 1.
+    :param step:
+        An integer giving the step of the sequence (same as the step argument in range).
+        It must not be 0.
 
-       This is suitable when the runtime of each chunk differs and is not
-       known in advance and therefore a larger number of smaller chunks
-       is used in order to keep all threads busy.
+    :param nogil:
+        This function can only be used with the GIL released.
+        If ``nogil`` is true, the loop will be wrapped in a nogil section.
 
-    guided:
-       As with dynamic scheduling, the iterations are distributed to
-       threads as they request them, but with decreasing chunk size.  The
-       size of each chunk is proportional to the number of unassigned
-       iterations divided by the number of participating threads,
-       decreasing to 1 (or the chunksize if provided).
+    :param schedule:
+        The ``schedule`` is passed to OpenMP and can be one of the following:
 
-       This has an advantage over pure dynamic scheduling when it turns
-       out that the last chunks take more time than expected or are
-       otherwise being badly scheduled, so that most threads start running
-       idle while the last chunks are being worked on by only a smaller
-       number of threads.
+        static:
+            If a chunksize is provided, iterations are distributed to all
+            threads ahead of time in blocks of the given chunksize.  If no
+            chunksize is given, the iteration space is divided into chunks that
+            are approximately equal in size, and at most one chunk is assigned
+            to each thread in advance.
 
-    runtime:
-       The schedule and chunk size are taken from the runtime scheduling
-       variable, which can be set through the ``openmp.omp_set_schedule()``
-       function call, or the OMP_SCHEDULE environment variable.  Note that
-       this essentially disables any static compile time optimisations of
-       the scheduling code itself and may therefore show a slightly worse
-       performance than when the same scheduling policy is statically
-       configured at compile time.
+            This is most appropriate when the scheduling overhead matters and
+            the problem can be cut down into equally sized chunks that are
+            known to have approximately the same runtime.
 
-    ..  auto             The decision regarding scheduling is delegated to the
-    ..                   compiler and/or runtime system. The programmer gives
-    ..                   the implementation the freedom to choose any possible
-    ..                   mapping of iterations to threads in the team.
+        dynamic:
+            The iterations are distributed to threads as they request them,
+            with a default chunk size of 1.
 
-    The default schedule is implementation defined. For more information consult
-    the OpenMP specification [#]_.
+            This is suitable when the runtime of each chunk differs and is not
+            known in advance and therefore a larger number of smaller chunks
+            is used in order to keep all threads busy.
 
-    The ``num_threads`` argument indicates how many threads the team should consist of. If not given,
-    OpenMP will decide how many threads to use. Typically this is the number of cores available on
-    the machine. However, this may be controlled through the ``omp_set_num_threads()`` function, or
-    through the ``OMP_NUM_THREADS`` environment variable.
+        guided:
+            As with dynamic scheduling, the iterations are distributed to
+            threads as they request them, but with decreasing chunk size.  The
+            size of each chunk is proportional to the number of unassigned
+            iterations divided by the number of participating threads,
+            decreasing to 1 (or the chunksize if provided).
 
-    The ``chunksize`` argument indicates the chunksize to be used for dividing the iterations among threads.
-    This is only valid for ``static``, ``dynamic`` and ``guided`` scheduling, and is optional. Different chunksizes
-    may give substantially different performance results, depending on the schedule, the load balance it provides,
-    the scheduling overhead and the amount of false sharing (if any).
+            This has an advantage over pure dynamic scheduling when it turns
+            out that the last chunks take more time than expected or are
+            otherwise being badly scheduled, so that most threads start running
+            idle while the last chunks are being worked on by only a smaller
+            number of threads.
 
-    Example with a reduction:
+        runtime:
+            The schedule and chunk size are taken from the runtime scheduling
+            variable, which can be set through the ``openmp.omp_set_schedule()``
+            function call, or the OMP_SCHEDULE environment variable.  Note that
+            this essentially disables any static compile time optimisations of
+            the scheduling code itself and may therefore show a slightly worse
+            performance than when the same scheduling policy is statically
+            configured at compile time.
+            The default schedule is implementation defined. For more information consult
+            the OpenMP specification [#]_.
 
-    .. literalinclude:: ../../examples/userguide/parallelism/simple_sum.pyx
+            ..  auto             The decision regarding scheduling is delegated to the
+            ..                   compiler and/or runtime system. The programmer gives
+            ..                   the implementation the freedom to choose any possible
+            ..                   mapping of iterations to threads in the team.
 
-    Example with a typed memoryview (e.g. a NumPy array)::
 
-        from cython.parallel import prange
 
-        def func(double[:] x, double alpha):
-            cdef Py_ssize_t i
+    :param num_threads:
+        The ``num_threads`` argument indicates how many threads the team should consist of. If not given,
+        OpenMP will decide how many threads to use. Typically this is the number of cores available on
+        the machine. However, this may be controlled through the ``omp_set_num_threads()`` function, or
+        through the ``OMP_NUM_THREADS`` environment variable.
 
-            for i in prange(x.shape[0]):
-                x[i] = alpha * x[i]
+    :param chunksize: 
+        The ``chunksize`` argument indicates the chunksize to be used for dividing the iterations among threads.
+        This is only valid for ``static``, ``dynamic`` and ``guided`` scheduling, and is optional. Different chunksizes
+        may give substantially different performance results, depending on the schedule, the load balance it provides,
+        the scheduling overhead and the amount of false sharing (if any).
+
+Example with a reduction:
+
+.. literalinclude:: ../../examples/userguide/parallelism/simple_sum.pyx
+
+Example with a typed memoryview (e.g. a NumPy array)::
+
+    from cython.parallel import prange
+
+    def func(double[:] x, double alpha):
+        cdef Py_ssize_t i
+
+        for i in prange(x.shape[0]):
+            x[i] = alpha * x[i]
 
 .. function:: parallel(num_threads=None)