Coverage for Lib/asyncio/tasks.py: 96%
551 statements
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-20 05:46 +0000
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-20 05:46 +0000
1"""Support for tasks, coroutines and the scheduler."""
3__all__ = (
4 'Task', 'create_task',
5 'FIRST_COMPLETED', 'FIRST_EXCEPTION', 'ALL_COMPLETED',
6 'wait', 'wait_for', 'as_completed', 'sleep',
7 'gather', 'shield', 'ensure_future', 'run_coroutine_threadsafe',
8 'current_task', 'all_tasks',
9 'create_eager_task_factory', 'eager_task_factory',
10 '_register_task', '_unregister_task', '_enter_task', '_leave_task',
11)
13import concurrent.futures
14import contextvars
15import functools
16import inspect
17import itertools
18import math
19import types
20import weakref
21from types import GenericAlias
23from . import base_tasks
24from . import coroutines
25from . import events
26from . import exceptions
27from . import futures
28from . import queues
29from . import timeouts
31# Helper to generate new task names
32# This uses itertools.count() instead of a "+= 1" operation because the latter
33# is not thread safe. See bpo-11866 for a longer explanation.
34_task_name_counter = itertools.count(1).__next__
37def current_task(loop=None):
38 """Return a currently executed task."""
39 if loop is None:
40 loop = events.get_running_loop()
41 return _current_tasks.get(loop)
44def all_tasks(loop=None):
45 """Return a set of all tasks for the loop."""
46 if loop is None:
47 loop = events.get_running_loop()
48 # capturing the set of eager tasks first, so if an eager task "graduates"
49 # to a regular task in another thread, we don't risk missing it.
50 eager_tasks = list(_eager_tasks)
52 return {t for t in itertools.chain(_scheduled_tasks, eager_tasks)
53 if futures._get_loop(t) is loop and not t.done()}
56class Task(futures._PyFuture): # Inherit Python Task implementation
57 # from a Python Future implementation.
59 """A coroutine wrapped in a Future."""
61 # An important invariant maintained while a Task not done:
62 # _fut_waiter is either None or a Future. The Future
63 # can be either done() or not done().
64 # The task can be in any of 3 states:
65 #
66 # - 1: _fut_waiter is not None and not _fut_waiter.done():
67 # __step() is *not* scheduled and the Task is waiting for _fut_waiter.
68 # - 2: (_fut_waiter is None or _fut_waiter.done()) and __step() is scheduled:
69 # the Task is waiting for __step() to be executed.
70 # - 3: _fut_waiter is None and __step() is *not* scheduled:
71 # the Task is currently executing (in __step()).
72 #
73 # * In state 1, one of the callbacks of __fut_waiter must be __wakeup().
74 # * The transition from 1 to 2 happens when _fut_waiter becomes done(),
75 # as it schedules __wakeup() to be called (which calls __step() so
76 # we way that __step() is scheduled).
77 # * It transitions from 2 to 3 when __step() is executed, and it clears
78 # _fut_waiter to None.
80 # If False, don't log a message if the task is destroyed while its
81 # status is still pending
82 _log_destroy_pending = True
84 def __init__(self, coro, *, loop=None, name=None, context=None,
85 eager_start=False):
86 super().__init__(loop=loop)
87 if self._source_traceback:
88 del self._source_traceback[-1]
89 if not coroutines.iscoroutine(coro):
90 # raise after Future.__init__(), attrs are required for __del__
91 # prevent logging for pending task in __del__
92 self._log_destroy_pending = False
93 raise TypeError(f"a coroutine was expected, got {coro!r}")
95 if name is None:
96 self._name = f'Task-{_task_name_counter()}'
97 else:
98 self._name = str(name)
100 self._num_cancels_requested = 0
101 self._must_cancel = False
102 self._fut_waiter = None
103 self._coro = coro
104 if context is None:
105 self._context = contextvars.copy_context()
106 elif not isinstance(context, contextvars.Context):
107 # gh-157301: the passed value must be a contextvars.Context
108 self._log_destroy_pending = False
109 raise TypeError('a contextvars.Context was expected, '
110 f'got {type(context).__name__}')
111 else:
112 self._context = context
114 if eager_start and self._loop.is_running():
115 try:
116 self.__eager_start()
117 except:
118 self._log_destroy_pending = False
119 raise
120 else:
121 self._loop.call_soon(self.__step, context=self._context)
122 _py_register_task(self)
124 def __del__(self):
125 if self._state == futures._PENDING and self._log_destroy_pending:
126 context = {
127 'task': self,
128 'message': 'Task was destroyed but it is pending!',
129 }
130 if self._source_traceback:
131 context['source_traceback'] = self._source_traceback
132 self._loop.call_exception_handler(context)
133 super().__del__()
135 __class_getitem__ = classmethod(GenericAlias)
137 def __repr__(self):
138 return base_tasks._task_repr(self)
140 def get_coro(self):
141 return self._coro
143 def get_context(self):
144 return self._context
146 def get_name(self):
147 return self._name
149 def set_name(self, value):
150 self._name = str(value)
152 def set_result(self, result):
153 raise RuntimeError('Task does not support set_result operation')
155 def set_exception(self, exception):
156 raise RuntimeError('Task does not support set_exception operation')
158 def get_stack(self, *, limit=None):
159 """Return the list of stack frames for this task's coroutine.
161 If the coroutine is not done, this returns the stack where it is
162 suspended. If the coroutine has completed successfully or was
163 cancelled, this returns an empty list. If the coroutine was
164 terminated by an exception, this returns the list of traceback
165 frames.
167 The frames are always ordered from oldest to newest.
169 The optional limit gives the maximum number of frames to
170 return; by default all available frames are returned. Its
171 meaning differs depending on whether a stack or a traceback is
172 returned: the newest frames of a stack are returned, but the
173 oldest frames of a traceback are returned. (This matches the
174 behavior of the traceback module.)
176 For reasons beyond our control, only one stack frame is
177 returned for a suspended coroutine.
178 """
179 return base_tasks._task_get_stack(self, limit)
181 def print_stack(self, *, limit=None, file=None):
182 """Print the stack or traceback for this task's coroutine.
184 This produces output similar to that of the traceback module,
185 for the frames retrieved by get_stack(). The limit argument
186 is passed to get_stack(). The file argument is an I/O stream
187 to which the output is written; by default output is written
188 to sys.stderr.
189 """
190 return base_tasks._task_print_stack(self, limit, file)
192 def cancel(self, msg=None):
193 """Request that this task cancel itself.
195 This arranges for a CancelledError to be thrown into the
196 wrapped coroutine on the next cycle through the event loop.
197 The coroutine then has a chance to clean up or even deny
198 the request using try/except/finally.
200 Unlike Future.cancel, this does not guarantee that the
201 task will be cancelled: the exception might be caught and
202 acted upon, delaying cancellation of the task or preventing
203 cancellation completely. The task may also return a value or
204 raise a different exception.
206 Immediately after this method is called, Task.cancelled() will
207 not return True (unless the task was already cancelled). A
208 task will be marked as cancelled when the wrapped coroutine
209 terminates with a CancelledError exception (even if cancel()
210 was not called).
212 This also increases the task's count of cancellation requests.
213 """
214 self._log_traceback = False
215 if self.done():
216 return False
217 self._num_cancels_requested += 1
218 # These two lines are controversial. See discussion starting at
219 # https://github.com/python/cpython/pull/31394#issuecomment-1053545331
220 # Also remember that this is duplicated in _asynciomodule.c.
221 # if self._num_cancels_requested > 1:
222 # return False
223 if self._fut_waiter is not None:
224 if self._fut_waiter.cancel(msg=msg):
225 # Leave self._fut_waiter; it may be a Task that
226 # catches and ignores the cancellation so we may have
227 # to cancel it again later.
228 return True
229 # It must be the case that self.__step is already scheduled.
230 self._must_cancel = True
231 self._cancel_message = msg
232 return True
234 def cancelling(self):
235 """Return the count of the task's cancellation requests.
237 This count is incremented when .cancel() is called
238 and may be decremented using .uncancel().
239 """
240 return self._num_cancels_requested
242 def uncancel(self):
243 """Decrement the task's count of cancellation requests.
245 This should be called by the party that called `cancel()` on the task
246 beforehand.
248 Returns the remaining number of cancellation requests.
249 """
250 if self._num_cancels_requested > 0: 250 ↛ 254line 250 didn't jump to line 254 because the condition on line 250 was always true
251 self._num_cancels_requested -= 1
252 if self._num_cancels_requested == 0: 252 ↛ 254line 252 didn't jump to line 254 because the condition on line 252 was always true
253 self._must_cancel = False
254 return self._num_cancels_requested
256 def __eager_start(self):
257 prev_task = _py_swap_current_task(self._loop, self)
258 try:
259 _py_register_eager_task(self)
260 # gh-157299: the eager step must record the awaited_by edge
261 futures.future_add_to_awaited_by(self, prev_task)
262 try:
263 self._context.run(self.__step_run_and_handle_result, None)
264 finally:
265 futures.future_discard_from_awaited_by(self, prev_task)
266 _py_unregister_eager_task(self)
267 finally:
268 try:
269 curtask = _py_swap_current_task(self._loop, prev_task)
270 assert curtask is self
271 finally:
272 if self.done():
273 self._coro = None
274 self = None # Needed to break cycles when an exception occurs.
275 else:
276 _py_register_task(self)
278 def __step(self, exc=None):
279 if self.done():
280 raise exceptions.InvalidStateError(
281 f'__step(): already done: {self!r}, {exc!r}')
282 if self._must_cancel:
283 # gh-108549: do not swallow SystemExit and KeyboardInterrupt.
284 if not isinstance(exc, (exceptions.CancelledError,
285 SystemExit, KeyboardInterrupt)):
286 exc = self._make_cancelled_error()
287 self._must_cancel = False
288 self._fut_waiter = None
290 _py_enter_task(self._loop, self)
291 try:
292 self.__step_run_and_handle_result(exc)
293 finally:
294 _py_leave_task(self._loop, self)
295 self = None # Needed to break cycles when an exception occurs.
297 def __step_run_and_handle_result(self, exc):
298 coro = self._coro
299 try:
300 if exc is None:
301 # We use the `send` method directly, because coroutines
302 # don't have `__iter__` and `__next__` methods.
303 result = coro.send(None)
304 else:
305 result = coro.throw(exc)
306 except StopIteration as exc:
307 if self._must_cancel:
308 # Task is cancelled right before coro stops.
309 self._must_cancel = False
310 super().cancel(msg=self._cancel_message)
311 else:
312 super().set_result(exc.value)
313 except exceptions.CancelledError as exc:
314 # Save the original exception so we can chain it later.
315 self._cancelled_exc = exc
316 super().cancel() # I.e., Future.cancel(self).
317 except (KeyboardInterrupt, SystemExit) as exc:
318 super().set_exception(exc)
319 raise
320 except BaseException as exc:
321 super().set_exception(exc)
322 else:
323 blocking = getattr(result, '_asyncio_future_blocking', None)
324 if blocking is not None:
325 # Yielded Future must come from Future.__iter__().
326 if futures._get_loop(result) is not self._loop:
327 new_exc = RuntimeError(
328 f'Task {self!r} got Future '
329 f'{result!r} attached to a different loop')
330 self._loop.call_soon(
331 self.__step, new_exc, context=self._context)
332 elif blocking: 332 ↛ 349line 332 didn't jump to line 349 because the condition on line 332 was always true
333 if result is self:
334 new_exc = RuntimeError(
335 f'Task cannot await on itself: {self!r}')
336 self._loop.call_soon(
337 self.__step, new_exc, context=self._context)
338 else:
339 futures.future_add_to_awaited_by(result, self)
340 result._asyncio_future_blocking = False
341 result.add_done_callback(
342 self.__wakeup, context=self._context)
343 self._fut_waiter = result
344 if self._must_cancel:
345 if self._fut_waiter.cancel( 345 ↛ 371line 345 didn't jump to line 371 because the condition on line 345 was always true
346 msg=self._cancel_message):
347 self._must_cancel = False
348 else:
349 new_exc = RuntimeError(
350 f'yield was used instead of yield from '
351 f'in task {self!r} with {result!r}')
352 self._loop.call_soon(
353 self.__step, new_exc, context=self._context)
355 elif result is None: 355 ↛ 358line 355 didn't jump to line 358 because the condition on line 355 was always true
356 # Bare yield relinquishes control for one event loop iteration.
357 self._loop.call_soon(self.__step, context=self._context)
358 elif inspect.isgenerator(result):
359 # Yielding a generator is just wrong.
360 new_exc = RuntimeError(
361 f'yield was used instead of yield from for '
362 f'generator in task {self!r} with {result!r}')
363 self._loop.call_soon(
364 self.__step, new_exc, context=self._context)
365 else:
366 # Yielding something else is an error.
367 new_exc = RuntimeError(f'Task got bad yield: {result!r}')
368 self._loop.call_soon(
369 self.__step, new_exc, context=self._context)
370 finally:
371 self = None # Needed to break cycles when an exception occurs.
373 def __wakeup(self, future):
374 futures.future_discard_from_awaited_by(future, self)
375 try:
376 future.result()
377 except BaseException as exc:
378 # This may also be a cancellation.
379 self.__step(exc)
380 else:
381 # Don't pass the value of `future.result()` explicitly,
382 # as `Future.__iter__` and `Future.__await__` don't need it.
383 # If we call `__step(value, None)` instead of `__step()`,
384 # Python eval loop would use `.send(value)` method call,
385 # instead of `__next__()`, which is slower for futures
386 # that return non-generator iterators from their `__iter__`.
387 self.__step()
388 self = None # Needed to break cycles when an exception occurs.
391_PyTask = Task
394try:
395 import _asyncio
396except ImportError:
397 pass
398else:
399 # _CTask is needed for tests.
400 Task = _CTask = _asyncio.Task
403def create_task(coro, **kwargs):
404 """Schedule the execution of a coroutine object in a spawn task.
406 Return a Task object.
407 """
408 loop = events.get_running_loop()
409 return loop.create_task(coro, **kwargs)
412# wait() and as_completed() similar to those in PEP 3148.
414FIRST_COMPLETED = concurrent.futures.FIRST_COMPLETED
415FIRST_EXCEPTION = concurrent.futures.FIRST_EXCEPTION
416ALL_COMPLETED = concurrent.futures.ALL_COMPLETED
419async def wait(fs, *, timeout=None, return_when=ALL_COMPLETED):
420 """Wait for the Futures or Tasks given by fs to complete.
422 The fs iterable must not be empty.
424 Returns two sets of Future: (done, pending).
426 Usage:
428 done, pending = await asyncio.wait(fs)
430 Note: This does not raise TimeoutError! Futures that aren't done
431 when the timeout occurs are returned in the second set.
432 """
433 if futures.isfuture(fs) or coroutines.iscoroutine(fs):
434 raise TypeError(f"expect a list of futures, not {type(fs).__name__}")
435 if not fs:
436 raise ValueError('Set of Tasks/Futures is empty.')
437 if return_when not in (FIRST_COMPLETED, FIRST_EXCEPTION, ALL_COMPLETED):
438 raise ValueError(f'Invalid return_when value: {return_when}')
440 fs = set(fs)
442 if any(coroutines.iscoroutine(f) for f in fs): 442 ↛ 443line 442 didn't jump to line 443 because the condition on line 442 was never true
443 raise TypeError("Passing coroutines is forbidden, use tasks explicitly.")
445 loop = events.get_running_loop()
446 return await _wait(fs, timeout, return_when, loop)
449def _release_waiter(waiter, *args):
450 if not waiter.done(): 450 ↛ exitline 450 didn't return from function '_release_waiter' because the condition on line 450 was always true
451 waiter.set_result(None)
454async def wait_for(fut, timeout):
455 """Wait for the single Future or coroutine to complete, with timeout.
457 Returns result of the Future or coroutine. When a timeout occurs,
458 it cancels fut and raises TimeoutError. To prevent fut from being
459 cancelled, wrap it in shield().
461 If the wait is cancelled, fut is also cancelled.
463 If fut suppresses the cancellation and returns a value instead,
464 that value is returned.
466 This function is a coroutine.
467 """
468 # The special case for timeout <= 0 is for the following case:
469 #
470 # async def test_waitfor():
471 # func_started = False
472 #
473 # async def func():
474 # nonlocal func_started
475 # func_started = True
476 #
477 # try:
478 # await asyncio.wait_for(func(), 0)
479 # except asyncio.TimeoutError:
480 # assert not func_started
481 # else:
482 # assert False
483 #
484 # asyncio.run(test_waitfor())
487 if timeout is not None and timeout <= 0:
488 fut = ensure_future(fut)
490 if fut.done():
491 return fut.result()
493 await _cancel_and_wait(fut)
494 try:
495 return fut.result()
496 except exceptions.CancelledError as exc:
497 raise TimeoutError from exc
499 async with timeouts.timeout(timeout):
500 return await fut
502async def _wait(fs, timeout, return_when, loop):
503 """Internal helper for wait().
505 The fs argument must be a collection of Futures.
506 """
507 assert fs, 'Set of Futures is empty.'
508 waiter = loop.create_future()
509 timeout_handle = None
510 if timeout is not None:
511 timeout_handle = loop.call_later(timeout, _release_waiter, waiter)
512 counter = len(fs)
513 cur_task = current_task()
515 def _on_completion(f):
516 nonlocal counter
517 counter -= 1
518 if (counter <= 0 or
519 return_when == FIRST_COMPLETED or
520 return_when == FIRST_EXCEPTION and (not f.cancelled() and
521 f.exception() is not None)):
522 if timeout_handle is not None: 522 ↛ 523line 522 didn't jump to line 523 because the condition on line 522 was never true
523 timeout_handle.cancel()
524 if not waiter.done():
525 waiter.set_result(None)
526 futures.future_discard_from_awaited_by(f, cur_task)
528 for f in fs:
529 f.add_done_callback(_on_completion)
530 futures.future_add_to_awaited_by(f, cur_task)
532 try:
533 await waiter
534 finally:
535 if timeout_handle is not None:
536 timeout_handle.cancel()
537 for f in fs:
538 f.remove_done_callback(_on_completion)
539 futures.future_discard_from_awaited_by(f, cur_task)
541 done, pending = set(), set()
542 for f in fs:
543 if f.done():
544 done.add(f)
545 else:
546 pending.add(f)
547 return done, pending
550async def _cancel_and_wait(fut):
551 """Cancel the *fut* future or task and wait until it completes."""
553 loop = events.get_running_loop()
554 waiter = loop.create_future()
555 cb = functools.partial(_release_waiter, waiter)
556 fut.add_done_callback(cb)
558 # gh-157058: awaiting the waiter leaves no edge on fut, add it here
559 cur_task = current_task()
560 futures.future_add_to_awaited_by(fut, cur_task)
562 try:
563 fut.cancel()
564 # We cannot wait on *fut* directly to make
565 # sure _cancel_and_wait itself is reliably cancellable.
566 await waiter
567 finally:
568 fut.remove_done_callback(cb)
569 futures.future_discard_from_awaited_by(fut, cur_task)
572class _AsCompletedIterator:
573 """Iterator of awaitables representing tasks of asyncio.as_completed.
575 As an asynchronous iterator, iteration yields futures as they finish. As a
576 plain iterator, new coroutines are yielded that will return or raise the
577 result of the next underlying future to complete.
578 """
579 def __init__(self, aws, timeout):
580 self._done = queues.Queue()
581 self._timeout_handle = None
583 loop = events.get_event_loop()
584 # The iterator may be created outside of a running event loop and
585 # then driven with loop.run_until_complete(), in which case there
586 # is no current task to record as the waiter.
587 if events._get_running_loop() is loop:
588 self._cur_task = current_task(loop)
589 else:
590 self._cur_task = None
591 todo = {ensure_future(aw, loop=loop) for aw in set(aws)}
592 for f in todo:
593 f.add_done_callback(self._handle_completion)
594 futures.future_add_to_awaited_by(f, self._cur_task)
595 if todo and timeout is not None:
596 self._timeout_handle = (
597 loop.call_later(timeout, self._handle_timeout)
598 )
599 self._todo = todo
600 self._todo_left = len(todo)
602 def __aiter__(self):
603 return self
605 def __iter__(self):
606 return self
608 async def __anext__(self):
609 if not self._todo_left:
610 raise StopAsyncIteration
611 assert self._todo_left > 0
612 self._todo_left -= 1
613 return await self._wait_for_one()
615 def __next__(self):
616 if not self._todo_left:
617 raise StopIteration
618 assert self._todo_left > 0
619 self._todo_left -= 1
620 return self._wait_for_one(resolve=True)
622 def _handle_timeout(self):
623 for f in self._todo:
624 f.remove_done_callback(self._handle_completion)
625 futures.future_discard_from_awaited_by(f, self._cur_task)
626 self._done.put_nowait(None) # Sentinel for _wait_for_one().
627 self._todo.clear() # Can't do todo.remove(f) in the loop.
629 def _handle_completion(self, f):
630 if not self._todo: 630 ↛ 631line 630 didn't jump to line 631 because the condition on line 630 was never true
631 return # _handle_timeout() was here first.
632 self._todo.remove(f)
633 futures.future_discard_from_awaited_by(f, self._cur_task)
634 self._done.put_nowait(f)
635 if not self._todo and self._timeout_handle is not None:
636 self._timeout_handle.cancel()
638 async def _wait_for_one(self, resolve=False):
639 # Wait for the next future to be done and return it unless resolve is
640 # set, in which case return either the result of the future or raise
641 # an exception.
642 try:
643 f = await self._done.get()
644 except:
645 self._todo_left += 1
646 raise
647 if f is None:
648 # Dummy value from _handle_timeout().
649 raise exceptions.TimeoutError
650 return f.result() if resolve else f
653def as_completed(fs, *, timeout=None):
654 """Create an iterator of awaitables or their results in completion order.
656 Run the supplied awaitables concurrently. The returned object can be
657 iterated to obtain the results of the awaitables as they finish.
659 The object returned can be iterated as an asynchronous iterator or
660 a plain iterator. When asynchronous iteration is used, the
661 originally-supplied awaitables are yielded if they are tasks or
662 futures. This makes it easy to correlate previously-scheduled tasks
663 with their results:
665 ipv4_connect = create_task(open_connection("127.0.0.1", 80))
666 ipv6_connect = create_task(open_connection("::1", 80))
667 tasks = [ipv4_connect, ipv6_connect]
669 async for earliest_connect in as_completed(tasks):
670 # earliest_connect is done. The result can be obtained by
671 # awaiting it or calling earliest_connect.result()
672 reader, writer = await earliest_connect
674 if earliest_connect is ipv6_connect:
675 print("IPv6 connection established.")
676 else:
677 print("IPv4 connection established.")
679 During asynchronous iteration, implicitly-created tasks will be
680 yielded for supplied awaitables that aren't tasks or futures.
682 When used as a plain iterator, each iteration yields a new coroutine
683 that returns the result or raises the exception of the next completed
684 awaitable. This pattern is compatible with Python versions older than
685 3.13:
687 ipv4_connect = create_task(open_connection("127.0.0.1", 80))
688 ipv6_connect = create_task(open_connection("::1", 80))
689 tasks = [ipv4_connect, ipv6_connect]
691 for next_connect in as_completed(tasks):
692 # next_connect is not one of the original task objects. It must
693 # be awaited to obtain the result value or raise the exception
694 # of the awaitable that finishes next.
695 reader, writer = await next_connect
697 A TimeoutError is raised if the timeout occurs before all awaitables
698 are done. This is raised by the async for loop during asynchronous
699 iteration or by the coroutines yielded during plain iteration.
700 """
701 if inspect.isawaitable(fs):
702 raise TypeError(
703 f"expects an iterable of awaitables, not {type(fs).__name__}"
704 )
706 return _AsCompletedIterator(fs, timeout)
709@types.coroutine
710def __sleep0():
711 """Skip one event loop run cycle.
713 This is a private helper for 'asyncio.sleep()', used
714 when the 'delay' is set to 0. It uses a bare 'yield'
715 expression (which Task.__step knows how to handle)
716 instead of creating a Future object.
717 """
718 yield
721async def sleep(delay, result=None):
722 """Coroutine that completes after a given time (in seconds)."""
723 if delay <= 0:
724 await __sleep0()
725 return result
727 if math.isnan(delay):
728 raise ValueError("Invalid delay: NaN (not a number)")
730 loop = events.get_running_loop()
731 future = loop.create_future()
732 h = loop.call_later(delay,
733 futures._set_result_unless_cancelled,
734 future, result)
735 try:
736 return await future
737 finally:
738 h.cancel()
741def ensure_future(coro_or_future, *, loop=None):
742 """Wrap a coroutine or an awaitable in a future.
744 If the argument is a Future, it is returned directly.
745 """
746 if futures.isfuture(coro_or_future):
747 if loop is not None and loop is not futures._get_loop(coro_or_future):
748 raise ValueError('The future belongs to a different loop than '
749 'the one specified as the loop argument')
750 return coro_or_future
751 should_close = True
752 if not coroutines.iscoroutine(coro_or_future):
753 if inspect.isawaitable(coro_or_future):
754 async def _wrap_awaitable(awaitable):
755 return await awaitable
757 coro_or_future = _wrap_awaitable(coro_or_future)
758 should_close = False
759 else:
760 raise TypeError('An asyncio.Future, a coroutine or an awaitable '
761 'is required')
763 if loop is None:
764 loop = events.get_event_loop()
765 try:
766 return loop.create_task(coro_or_future)
767 except RuntimeError:
768 if should_close: 768 ↛ 770line 768 didn't jump to line 770 because the condition on line 768 was always true
769 coro_or_future.close()
770 raise
773class _GatheringFuture(futures.Future):
774 """Helper for gather().
776 This overrides cancel() to cancel all the children and act more
777 like Task.cancel(), which doesn't immediately mark itself as
778 cancelled.
779 """
781 def __init__(self, children, *, loop):
782 assert loop is not None
783 super().__init__(loop=loop)
784 self._children = children
785 self._cancel_requested = False
787 def cancel(self, msg=None):
788 if self.done():
789 return False
790 ret = False
791 for child in self._children:
792 if child.cancel(msg=msg):
793 ret = True
794 if ret:
795 # If any child tasks were actually cancelled, we should
796 # propagate the cancellation request regardless of
797 # *return_exceptions* argument. See issue 32684.
798 self._cancel_requested = True
799 return ret
802def _discard_awaited_by(children, waiter):
803 for fut in children:
804 futures.future_discard_from_awaited_by(fut, waiter)
807def gather(*coros_or_futures, return_exceptions=False):
808 """Return a future aggregating results from the given coroutines/futures.
810 Coroutines will be wrapped in a future and scheduled in the event
811 loop. They will not necessarily be scheduled in the same order as
812 passed in.
814 All futures must share the same event loop. If all the tasks are
815 done successfully, the returned future's result is the list of
816 results (in the order of the original sequence, not necessarily
817 the order of results arrival). If *return_exceptions* is True,
818 exceptions in the tasks are treated the same as successful
819 results, and gathered in the result list; otherwise, the first
820 raised exception will be immediately propagated to the returned
821 future.
823 Cancellation: if the outer Future is cancelled, all children (that
824 have not completed yet) are also cancelled. If any child is
825 cancelled, this is treated as if it raised CancelledError --
826 the outer Future is *not* cancelled in this case. (This is to
827 prevent the cancellation of one child to cause other children to
828 be cancelled.)
830 If *return_exceptions* is False, cancelling gather() after it
831 has been marked done won't cancel any submitted awaitables.
832 For instance, gather can be marked done after propagating an
833 exception to the caller, therefore, calling ``gather.cancel()``
834 after catching an exception (raised by one of the awaitables) from
835 gather won't cancel any other awaitables.
836 """
837 if not coros_or_futures:
838 loop = events.get_event_loop()
839 outer = loop.create_future()
840 outer.set_result([])
841 return outer
843 loop = events._get_running_loop()
844 if loop is not None:
845 cur_task = current_task(loop)
846 else:
847 cur_task = None
849 def _done_callback(fut, cur_task=cur_task):
850 nonlocal nfinished
851 nfinished += 1
853 if cur_task is not None:
854 futures.future_discard_from_awaited_by(fut, cur_task)
856 if outer is None or outer.done():
857 if not fut.cancelled():
858 # Mark exception retrieved.
859 fut.exception()
860 return
862 if not return_exceptions:
863 if fut.cancelled():
864 # Check if 'fut' is cancelled first, as
865 # 'fut.exception()' will *raise* a CancelledError
866 # instead of returning it.
867 exc = fut._make_cancelled_error()
868 # gh-157213: children outliving gather() must lose the edge
869 _discard_awaited_by(children, cur_task)
870 outer.set_exception(exc)
871 return
872 else:
873 exc = fut.exception()
874 if exc is not None:
875 _discard_awaited_by(children, cur_task)
876 outer.set_exception(exc)
877 return
879 if nfinished == nfuts:
880 # All futures are done; create a list of results
881 # and set it to the 'outer' future.
882 results = []
884 for fut in children:
885 if fut.cancelled():
886 # Check if 'fut' is cancelled first, as 'fut.exception()'
887 # will *raise* a CancelledError instead of returning it.
888 # Also, since we're adding the exception return value
889 # to 'results' instead of raising it, don't bother
890 # setting __context__. This also lets us preserve
891 # calling '_make_cancelled_error()' at most once.
892 res = exceptions.CancelledError(
893 '' if fut._cancel_message is None else
894 fut._cancel_message)
895 else:
896 res = fut.exception()
897 if res is None:
898 res = fut.result()
899 results.append(res)
901 if outer._cancel_requested:
902 # If gather is being cancelled we must propagate the
903 # cancellation regardless of *return_exceptions* argument.
904 # See issue 32684.
905 exc = fut._make_cancelled_error()
906 outer.set_exception(exc)
907 else:
908 outer.set_result(results)
910 arg_to_fut = {}
911 children = []
912 nfuts = 0
913 nfinished = 0
914 done_futs = []
915 outer = None # bpo-46672
916 for arg in coros_or_futures:
917 if arg not in arg_to_fut:
918 fut = ensure_future(arg, loop=loop)
919 if loop is None:
920 loop = futures._get_loop(fut)
921 if fut is not arg:
922 # 'arg' was not a Future, therefore, 'fut' is a new
923 # Future created specifically for 'arg'. Since the caller
924 # can't control it, disable the "destroy pending task"
925 # warning.
926 fut._log_destroy_pending = False
927 nfuts += 1
928 arg_to_fut[arg] = fut
929 if fut.done():
930 done_futs.append(fut)
931 else:
932 fut.add_done_callback(_done_callback)
934 else:
935 # There's a duplicate Future object in coros_or_futures.
936 fut = arg_to_fut[arg]
938 children.append(fut)
940 outer = _GatheringFuture(children, loop=loop)
941 # Add the awaited-by edges only after all arguments are validated
942 if cur_task is not None and len(done_futs) < nfuts:
943 for fut in arg_to_fut.values():
944 if not fut.done():
945 futures.future_add_to_awaited_by(fut, cur_task)
946 # Run done callbacks after GatheringFuture created so any post-processing
947 # can be performed at this point
948 # optimization: in the special case that *all* futures finished eagerly,
949 # this will effectively complete the gather eagerly, with the last
950 # callback setting the result (or exception) on outer before returning it
951 for fut in done_futs:
952 _done_callback(fut)
953 return outer
956def shield(arg):
957 """Wait for a future, shielding it from cancellation.
959 The statement
961 task = asyncio.create_task(something())
962 res = await shield(task)
964 is exactly equivalent to the statement
966 res = await something()
968 *except* that if the coroutine containing it is cancelled, the
969 task running in something() is not cancelled. From the POV of
970 something(), the cancellation did not happen. But its caller is
971 still cancelled, so the yield-from expression still raises
972 CancelledError. Note: If something() is cancelled by other means
973 this will still cancel shield().
975 If you want to completely ignore cancellation (not recommended)
976 you can combine shield() with a try/except clause, as follows:
978 task = asyncio.create_task(something())
979 try:
980 res = await shield(task)
981 except CancelledError:
982 res = None
984 Save a reference to tasks passed to this function, to avoid
985 a task disappearing mid-execution. The event loop only keeps
986 weak references to tasks. A task that isn't referenced elsewhere
987 may get garbage collected at any time, even before it's done.
988 """
989 inner = ensure_future(arg)
990 if inner.done():
991 # Shortcut.
992 return inner
993 loop = futures._get_loop(inner)
994 outer = loop.create_future()
996 if loop is not None and (cur_task := current_task(loop)) is not None:
997 futures.future_add_to_awaited_by(inner, cur_task)
998 else:
999 cur_task = None
1001 def _clear_awaited_by_callback(inner):
1002 futures.future_discard_from_awaited_by(inner, cur_task)
1004 def _inner_done_callback(inner):
1005 if outer.cancelled(): 1005 ↛ 1006line 1005 didn't jump to line 1006 because the condition on line 1005 was never true
1006 return
1008 if inner.cancelled():
1009 outer.cancel()
1010 else:
1011 exc = inner.exception()
1012 if exc is not None:
1013 outer.set_exception(exc)
1014 else:
1015 outer.set_result(inner.result())
1017 def _outer_done_callback(outer):
1018 if not inner.done():
1019 inner.remove_done_callback(_inner_done_callback)
1020 if cur_task is not None:
1021 inner.remove_done_callback(_clear_awaited_by_callback)
1022 futures.future_discard_from_awaited_by(inner, cur_task)
1024 if cur_task is not None:
1025 inner.add_done_callback(_clear_awaited_by_callback)
1028 inner.add_done_callback(_inner_done_callback)
1029 outer.add_done_callback(_outer_done_callback)
1030 return outer
1033def run_coroutine_threadsafe(coro, loop):
1034 """Submit a coroutine object to a given event loop.
1036 Return a concurrent.futures.Future to access the result.
1037 """
1038 if not coroutines.iscoroutine(coro): 1038 ↛ 1039line 1038 didn't jump to line 1039 because the condition on line 1038 was never true
1039 raise TypeError('A coroutine object is required')
1040 future = concurrent.futures.Future()
1042 def callback():
1043 try:
1044 futures._chain_future(ensure_future(coro, loop=loop), future)
1045 except (SystemExit, KeyboardInterrupt):
1046 raise
1047 except BaseException as exc:
1048 if future.set_running_or_notify_cancel(): 1048 ↛ 1050line 1048 didn't jump to line 1050 because the condition on line 1048 was always true
1049 future.set_exception(exc)
1050 raise
1052 loop.call_soon_threadsafe(callback)
1053 return future
1056def create_eager_task_factory(custom_task_constructor):
1057 """Create a function suitable for use as a task factory on an event-loop.
1059 Example usage:
1061 loop.set_task_factory(
1062 asyncio.create_eager_task_factory(my_task_constructor))
1064 Now, tasks created will be started immediately (rather than being first
1065 scheduled to an event loop). The constructor argument can be any
1066 callable that returns a Task-compatible object and has a signature
1067 compatible with `Task.__init__`; it must have the `eager_start`
1068 keyword argument.
1070 Most applications will use `Task` for `custom_task_constructor` and in
1071 this case there's no need to call `create_eager_task_factory()`
1072 directly. Instead the global `eager_task_factory` instance can be
1073 used. E.g. `loop.set_task_factory(asyncio.eager_task_factory)`.
1074 """
1076 def factory(loop, coro, *, eager_start=True, **kwargs):
1077 return custom_task_constructor(
1078 coro, loop=loop, eager_start=eager_start, **kwargs)
1080 return factory
1083eager_task_factory = create_eager_task_factory(Task)
1086# Collectively these two sets hold references to the complete set of active
1087# tasks. Eagerly executed tasks use a faster regular set as an optimization
1088# but may graduate to a WeakSet if the task blocks on IO.
1089_scheduled_tasks = weakref.WeakSet()
1090_eager_tasks = set()
1092# Dictionary containing tasks that are currently active in
1093# all running event loops. {EventLoop: Task}
1094_current_tasks = {}
1097def _register_task(task):
1098 """Register an asyncio Task scheduled to run on an event loop."""
1099 _scheduled_tasks.add(task)
1102def _register_eager_task(task):
1103 """Register an asyncio Task about to be eagerly executed."""
1104 _eager_tasks.add(task)
1107def _enter_task(loop, task):
1108 current_task = _current_tasks.get(loop)
1109 if current_task is not None:
1110 raise RuntimeError(f"Cannot enter into task {task!r} while another "
1111 f"task {current_task!r} is being executed.")
1112 _current_tasks[loop] = task
1115def _leave_task(loop, task):
1116 current_task = _current_tasks.get(loop)
1117 if current_task is not task:
1118 raise RuntimeError(f"Leaving task {task!r} does not match "
1119 f"the current task {current_task!r}.")
1120 del _current_tasks[loop]
1123def _swap_current_task(loop, task):
1124 prev_task = _current_tasks.get(loop)
1125 if task is None:
1126 del _current_tasks[loop]
1127 else:
1128 _current_tasks[loop] = task
1129 return prev_task
1132def _unregister_task(task):
1133 """Unregister a completed, scheduled Task."""
1134 _scheduled_tasks.discard(task)
1137def _unregister_eager_task(task):
1138 """Unregister a task which finished its first eager step."""
1139 _eager_tasks.discard(task)
1142_py_current_task = current_task
1143_py_register_task = _register_task
1144_py_register_eager_task = _register_eager_task
1145_py_unregister_task = _unregister_task
1146_py_unregister_eager_task = _unregister_eager_task
1147_py_enter_task = _enter_task
1148_py_leave_task = _leave_task
1149_py_swap_current_task = _swap_current_task
1150_py_all_tasks = all_tasks
1152try:
1153 from _asyncio import (_register_task, _register_eager_task,
1154 _unregister_task, _unregister_eager_task,
1155 _enter_task, _leave_task, _swap_current_task,
1156 current_task, all_tasks)
1157except ImportError:
1158 pass
1159else:
1160 _c_current_task = current_task
1161 _c_register_task = _register_task
1162 _c_register_eager_task = _register_eager_task
1163 _c_unregister_task = _unregister_task
1164 _c_unregister_eager_task = _unregister_eager_task
1165 _c_enter_task = _enter_task
1166 _c_leave_task = _leave_task
1167 _c_swap_current_task = _swap_current_task
1168 _c_all_tasks = all_tasks