bpo-32306: Clarify c.f.Executor.map() documentation (GH-4947) (#4948) · python/cpython@4aa84e7 (original) (raw)
`@@ -40,21 +40,29 @@ Executor Objects
`
40
40
``
41
41
` .. method:: map(func, *iterables, timeout=None, chunksize=1)
`
42
42
``
43
``
`` -
Equivalent to :func:map(func, *iterables) <map> except func is executed
``
44
``
`-
asynchronously and several calls to func may be made concurrently. The
`
45
``
`` -
returned iterator raises a :exc:concurrent.futures.TimeoutError if
``
46
``
`` -
:meth:~iterator.__next__ is called and the result isn't available
``
``
43
`` +
Similar to :func:map(func, *iterables) <map> except:
``
``
44
+
``
45
`+
- the iterables are collected immediately rather than lazily;
`
``
46
+
``
47
`+
- func is executed asynchronously and several calls to
`
``
48
`+
func may be made concurrently.
`
``
49
+
``
50
`` +
The returned iterator raises a :exc:concurrent.futures.TimeoutError
``
``
51
`` +
if :meth:~iterator.__next__ is called and the result isn't available
``
47
52
`` after timeout seconds from the original call to :meth:Executor.map.
``
48
53
` timeout can be an int or a float. If timeout is not specified or
`
49
``
``None``, there is no limit to the wait time. If a call raises an
50
``
`-
exception, then that exception will be raised when its value is
`
51
``
`` -
retrieved from the iterator. When using :class:ProcessPoolExecutor, this
``
52
``
`-
method chops iterables into a number of chunks which it submits to the
`
53
``
`-
pool as separate tasks. The (approximate) size of these chunks can be
`
54
``
`-
specified by setting chunksize to a positive integer. For very long
`
55
``
`-
iterables, using a large value for chunksize can significantly improve
`
56
``
`` -
performance compared to the default size of 1. With :class:ThreadPoolExecutor,
``
57
``
`-
chunksize has no effect.
`
``
54
``None``, there is no limit to the wait time.
``
55
+
``
56
`+
If a func call raises an exception, then that exception will be
`
``
57
`+
raised when its value is retrieved from the iterator.
`
``
58
+
``
59
`` +
When using :class:ProcessPoolExecutor, this method chops iterables
``
``
60
`+
into a number of chunks which it submits to the pool as separate
`
``
61
`+
tasks. The (approximate) size of these chunks can be specified by
`
``
62
`+
setting chunksize to a positive integer. For very long iterables,
`
``
63
`+
using a large value for chunksize can significantly improve
`
``
64
`+
performance compared to the default size of 1. With
`
``
65
`` +
:class:ThreadPoolExecutor, chunksize has no effect.
``
58
66
``
59
67
` .. versionchanged:: 3.5
`
60
68
` Added the chunksize argument.
`