Skip to content

C
cython
Commit aa8f3b1c authored by gabrieldemarmiesse's avatar gabrieldemarmiesse
Browse files
Options

Changed the organization of the description of the function prange to make it... 

Changed the organization of the description of the function prange to make it easier for readers to jump to the information that they want.
parent 04780910
Hide whitespace changes
Inline Side-by-side
Showing with 77 additions and 60 deletions
docs/src/userguide/parallelism.rst
View file @ aa8f3b1c
......@@ -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)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7