Update docs and cancel all on timeout.

Author: serhiy-storchaka

Doc/library/concurrent.futures.rst

@@ -51,11 +51,18 @@ Executor Objects
       The returned iterator raises a :exc:`TimeoutError`
       if :meth:`~iterator.__next__` is called and the result isn't available
       after *timeout* seconds from the original call to :meth:`Executor.map`.
-      *timeout* can be an int or a float.  If *timeout* is not specified or
+      *timeout* can be an int or a float.
+      It cancels all future calls of *fn* and closes the iterator.
+      If *timeout* is not specified or
       ``None``, there is no limit to the wait time.
 
       If a *fn* call raises an exception, then that exception will be
       raised when its value is retrieved from the iterator.
+      It does not cancel future calls of *fn*.
+
+      The returned iterator has method :meth:`!close` which cancels all
+      future calls of *fn* and discards the results of already finished calls
+      if they are available.
 
       When using :class:`ProcessPoolExecutor`, this method chops *iterables*
       into a number of chunks which it submits to the pool as separate
@@ -68,6 +75,10 @@ Executor Objects
       .. versionchanged:: 3.5
          Added the *chunksize* argument.
 
+      .. versionchanged:: 3.13
+         The returned iterator no longer automatically closed if a *fn* call
+         raises an exception.
+
    .. method:: shutdown(wait=True, *, cancel_futures=False)
 
       Signal the executor that it should free any resources that it is using

Doc/whatsnew/3.13.rst

@@ -144,6 +144,11 @@ Other Language Changes
   (Contributed by Levi Sabah, Zackery Spytz and Hugo van Kemenade in
   :gh:`73965`.)
 
+* The iterator returned by :meth:`concurrent.futures.Executor.map` is no longer
+  automatically closed if a function call raises an exception.
+  Use method :meth:`!close` to explicitly close the iterator.
+  (Contributed by xzmeng and Serhiy Storchaka in :gh:`108518`.)
+
 New Modules
 ===========
 

Lib/concurrent/futures/_base.py

@@ -315,6 +315,8 @@ def _result_or_cancel(fut, timeout=None):
     try:
         try:
             return (fut.result(timeout), None)
+        except TimeoutError:
+            raise
         except BaseException as exc:
             return (None, exc)
         finally:

Lib/test/test_concurrent_futures/executor.py

@@ -49,48 +49,42 @@ def test_map(self):
 
     def test_map_exception(self):
         i = self.executor.map(divmod, [5, 5, 5, 5], [2, 3, 0, 5])
-        self.assertEqual(i.__next__(), (2, 1))
-        self.assertEqual(i.__next__(), (1, 2))
-        self.assertRaises(ZeroDivisionError, i.__next__)
-        self.assertEqual(i.__next__(), (1, 0))
-        self.assertRaises(StopIteration, i.__next__)
-        self.assertRaises(StopIteration, i.__next__)
+        self.assertEqual(next(i), (2, 1))
+        self.assertEqual(next(i), (1, 2))
+        self.assertRaises(ZeroDivisionError, next, i)
+        self.assertEqual(next(i), (1, 0))
+        self.assertRaises(StopIteration, next, i)
+        self.assertRaises(StopIteration, next, i)
 
         i = self.executor.map(divmod, [5, 5, 5, 5], [2, 0, 3, 5], chunksize=3)
-        self.assertEqual(i.__next__(), (2, 1))
-        self.assertRaises(ZeroDivisionError, i.__next__)
-        self.assertEqual(i.__next__(), (1, 2))
-        self.assertEqual(i.__next__(), (1, 0))
-        self.assertRaises(StopIteration, i.__next__)
-        self.assertRaises(StopIteration, i.__next__)
+        self.assertEqual(next(i), (2, 1))
+        self.assertRaises(ZeroDivisionError, next, i)
+        self.assertEqual(next(i), (1, 2))
+        self.assertEqual(next(i), (1, 0))
+        self.assertRaises(StopIteration, next, i)
+        self.assertRaises(StopIteration, next, i)
 
     @support.requires_resource('walltime')
     def test_map_timeout(self):
-        results = []
-        try:
-            for i in self.executor.map(time.sleep,
-                                       [0, 0, 6],
-                                       timeout=5):
-                results.append(i)
-        except futures.TimeoutError:
-            pass
-        else:
-            self.fail('expected TimeoutError')
-
-        self.assertEqual([None, None], results)
+        i = self.executor.map(time.sleep, [0, 0, 6, 0], timeout=5)
+        next(i)
+        next(i)
+        self.assertRaises(futures.TimeoutError, next, i)
+        self.assertRaises(StopIteration, next, i)
+        self.assertRaises(StopIteration, next, i)
 
     def test_map_close(self):
         i = self.executor.map(divmod, [5, 5, 5, 5], [2, 0, 3, 5])
-        self.assertEqual(i.__next__(), (2, 1))
+        self.assertEqual(next(i), (2, 1))
         i.close()
-        self.assertRaises(StopIteration, i.__next__)
-        self.assertRaises(StopIteration, i.__next__)
+        self.assertRaises(StopIteration, next, i)
+        self.assertRaises(StopIteration, next, i)
 
         i = self.executor.map(divmod, [5, 5, 5, 5], [2, 0, 3, 5], chunksize=3)
-        self.assertEqual(i.__next__(), (2, 1))
+        self.assertEqual(next(i), (2, 1))
         i.close()
-        self.assertRaises(StopIteration, i.__next__)
-        self.assertRaises(StopIteration, i.__next__)
+        self.assertRaises(StopIteration, next, i)
+        self.assertRaises(StopIteration, next, i)
 
     def test_shutdown_race_issue12456(self):
         # Issue #12456: race condition at shutdown where trying to post a

Misc/NEWS.d/next/Library/2024-02-04-13-56-48.gh-issue-108518.6NCPk_.rst

@@ -0,0 +1,3 @@
+The iterator returned by :meth:`concurrent.futures.Executor.map` is no longer
+automatically closed if a function call raises an exception.
+Use method :meth:`!close` to explicitly close the iterator.