Debian Codegraph @

Lib/asyncio/taskgroups.py

raw
1 # Adapted with permission from the EdgeDB project;
2 # license: PSFL.
3
4
5 __all__ = ("TaskGroup",)
6
7 from . import events
8 from . import exceptions
9 from . import tasks
10
11
12 class TaskGroup:
13 """Asynchronous context manager for managing groups of tasks.
14
15 Example use:
16
17 async with asyncio.TaskGroup() as group:
18 task1 = group.create_task(some_coroutine(...))
19 task2 = group.create_task(other_coroutine(...))
20 print("Both tasks have completed now.")
21
22 All tasks are awaited when the context manager exits.
23
24 Any exceptions other than `asyncio.CancelledError` raised within
25 a task will cancel all remaining tasks and wait for them to exit.
26 The exceptions are then combined and raised as an `ExceptionGroup`.
27 """
28 def __init__(self):
29 self._entered = False
30 self._exiting = False
31 self._aborting = False
32 self._loop = None
33 self._parent_task = None
34 self._parent_cancel_requested = False
35 self._tasks = set()
36 self._errors = []
37 self._base_error = None
38 self._on_completed_fut = None
39
40 def __repr__(self):
41 info = ['']
42 if self._tasks:
43 info.append(f'tasks={len(self._tasks)}')
44 if self._errors:
45 info.append(f'errors={len(self._errors)}')
46 if self._aborting:
47 info.append('cancelling')
48 elif self._entered:
49 info.append('entered')
50
51 info_str = ' '.join(info)
52 return f'<TaskGroup{info_str}>'
53
54 async def __aenter__(self):
55 if self._entered:
56 raise RuntimeError(
57 f"TaskGroup {self!r} has already been entered")
58 if self._loop is None:
59 self._loop = events.get_running_loop()
60 self._parent_task = tasks.current_task(self._loop)
61 if self._parent_task is None:
62 raise RuntimeError(
63 f'TaskGroup {self!r} cannot determine the parent task')
64 self._entered = True
65
66 return self
67
68 async def __aexit__(self, et, exc, tb):
69 tb = None
70 try:
71 return await self._aexit(et, exc)
72 finally:
73 # Exceptions are heavy objects that can have object
74 # cycles (bad for GC); let's not keep a reference to
75 # a bunch of them. It would be nicer to use a try/finally
76 # in __aexit__ directly but that introduced some diff noise
77 self._parent_task = None
78 self._errors = None
79 self._base_error = None
80 exc = None
81
82 async def _aexit(self, et, exc):
83 self._exiting = True
84
85 if (exc is not None and
86 self._is_base_error(exc) and
87 self._base_error is None):
88 self._base_error = exc
89
90 if et is not None and issubclass(et, exceptions.CancelledError):
91 propagate_cancellation_error = exc
92 else:
93 propagate_cancellation_error = None
94
95 if et is not None:
96 if not self._aborting:
97 # Our parent task is being cancelled:
98 #
99 # async with TaskGroup() as g:
100 # g.create_task(...)
101 # await ... # <- CancelledError
102 #
103 # or there's an exception in "async with":
104 #
105 # async with TaskGroup() as g:
106 # g.create_task(...)
107 # 1 / 0
108 #
109 self._abort()
110
111 # We use while-loop here because "self._on_completed_fut"
112 # can be cancelled multiple times if our parent task
113 # is being cancelled repeatedly (or even once, when
114 # our own cancellation is already in progress)
115 while self._tasks:
116 if self._on_completed_fut is None:
117 self._on_completed_fut = self._loop.create_future()
118
119 try:
120 await self._on_completed_fut
121 except exceptions.CancelledError as ex:
122 if not self._aborting:
123 # Our parent task is being cancelled:
124 #
125 # async def wrapper():
126 # async with TaskGroup() as g:
127 # g.create_task(foo)
128 #
129 # "wrapper" is being cancelled while "foo" is
130 # still running.
131 propagate_cancellation_error = ex
132 self._abort()
133
134 self._on_completed_fut = None
135
136 assert not self._tasks
137
138 if self._base_error is not None:
139 try:
140 raise self._base_error
141 finally:
142 exc = None
143
144 if self._parent_cancel_requested:
145 # If this flag is set we *must* call uncancel().
146 if self._parent_task.uncancel() == 0:
147 # If there are no pending cancellations left,
148 # don't propagate CancelledError.
149 propagate_cancellation_error = None
150
151 # Propagate CancelledError if there is one, except if there
152 # are other errors -- those have priority.
153 try:
154 if propagate_cancellation_error is not None and not self._errors:
155 try:
156 raise propagate_cancellation_error
157 finally:
158 exc = None
159 finally:
160 propagate_cancellation_error = None
161
162 if et is not None and not issubclass(et, exceptions.CancelledError):
163 self._errors.append(exc)
164
165 if self._errors:
166 # If the parent task is being cancelled from the outside
167 # of the taskgroup, un-cancel and re-cancel the parent task,
168 # which will keep the cancel count stable.
169 if self._parent_task.cancelling():
170 self._parent_task.uncancel()
171 self._parent_task.cancel()
172 try:
173 raise BaseExceptionGroup(
174 'unhandled errors in a TaskGroup',
175 self._errors,
176 ) from None
177 finally:
178 exc = None
179
180
181 def create_task(self, coro, *, name=None, context=None):
182 """Create a new task in this group and return it.
183
184 Similar to `asyncio.create_task`.
185 """
186 if not self._entered:
187 coro.close()
188 raise RuntimeError(f"TaskGroup {self!r} has not been entered")
189 if self._exiting and not self._tasks:
190 coro.close()
191 raise RuntimeError(f"TaskGroup {self!r} is finished")
192 if self._aborting:
193 coro.close()
194 raise RuntimeError(f"TaskGroup {self!r} is shutting down")
195 if context is None:
196 task = self._loop.create_task(coro, name=name)
197 else:
198 task = self._loop.create_task(coro, name=name, context=context)
199
200 # Always schedule the done callback even if the task is
201 # already done (e.g. if the coro was able to complete eagerly),
202 # otherwise if the task completes with an exception then it will cancel
203 # the current task too early. gh-128550, gh-128588
204 self._tasks.add(task)
205 task.add_done_callback(self._on_task_done)
206 try:
207 return task
208 finally:
209 # gh-128552: prevent a refcycle of
210 # task.exception().__traceback__->TaskGroup.create_task->task
211 del task
212
213 # Since Python 3.8 Tasks propagate all exceptions correctly,
214 # except for KeyboardInterrupt and SystemExit which are
215 # still considered special.
216
217 def _is_base_error(self, exc: BaseException) -> bool:
218 assert isinstance(exc, BaseException)
219 return isinstance(exc, (SystemExit, KeyboardInterrupt))
220
221 def _abort(self):
222 self._aborting = True
223
224 for t in self._tasks:
225 if not t.done():
226 t.cancel()
227
228 def _on_task_done(self, task):
229 self._tasks.discard(task)
230
231 if self._on_completed_fut is not None and not self._tasks:
232 if not self._on_completed_fut.done():
233 self._on_completed_fut.set_result(True)
234
235 if task.cancelled():
236 return
237
238 exc = task.exception()
239 if exc is None:
240 return
241
242 self._errors.append(exc)
243 if self._is_base_error(exc) and self._base_error is None:
244 self._base_error = exc
245
246 if self._parent_task.done():
247 # Not sure if this case is possible, but we want to handle
248 # it anyways.
249 self._loop.call_exception_handler({
250 'message': f'Task {task!r} has errored out but its parent '
251 f'task {self._parent_task} is already completed',
252 'exception': exc,
253 'task': task,
254 })
255 return
256
257 if not self._aborting and not self._parent_cancel_requested:
258 # If parent task *is not* being cancelled, it means that we want
259 # to manually cancel it to abort whatever is being run right now
260 # in the TaskGroup. But we want to mark parent task as
261 # "not cancelled" later in __aexit__. Example situation that
262 # we need to handle:
263 #
264 # async def foo():
265 # try:
266 # async with TaskGroup() as g:
267 # g.create_task(crash_soon())
268 # await something # <- this needs to be canceled
269 # # by the TaskGroup, e.g.
270 # # foo() needs to be cancelled
271 # except Exception:
272 # # Ignore any exceptions raised in the TaskGroup
273 # pass
274 # await something_else # this line has to be called
275 # # after TaskGroup is finished.
276 self._abort()
277 self._parent_cancel_requested = True
278 self._parent_task.cancel()