Coverage for Lib/asyncio/tools.py: 79%
192 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"""Tools to analyze tasks running in asyncio programs."""
3from collections import defaultdict
4from itertools import count
5from enum import Enum
6import sys
7from _remote_debugging import RemoteUnwinder, FrameInfo
9class NodeType(Enum):
10 COROUTINE = 1
11 TASK = 2
14class CycleFoundException(Exception):
15 """Raised when there is a cycle when drawing the call tree."""
16 def __init__(
17 self,
18 cycles: list[list[int]],
19 id2name: dict[int, str],
20 ) -> None:
21 super().__init__(cycles, id2name)
22 self.cycles = cycles
23 self.id2name = id2name
27# ─── indexing helpers ───────────────────────────────────────────
28def _format_stack_entry(elem: str|FrameInfo) -> str:
29 if not isinstance(elem, str): 29 ↛ 38line 29 didn't jump to line 38 because the condition on line 29 was always true
30 if elem.location is None:
31 if elem.filename in ("", "~"):
32 return f"{elem.funcname}"
33 return f"{elem.funcname} {elem.filename}"
34 if elem.location.lineno == 0 and elem.filename == "":
35 return f"{elem.funcname}"
36 else:
37 return f"{elem.funcname} {elem.filename}:{elem.location.lineno}"
38 return elem
41def _index(result):
42 id2name, awaits, task_stacks = {}, [], {}
43 for awaited_info in result:
44 for task_info in awaited_info.awaited_by:
45 task_id = task_info.task_id
46 task_name = task_info.task_name
47 id2name[task_id] = task_name
49 # Store the internal coroutine stack for this task
50 if task_info.coroutine_stack:
51 for coro_info in task_info.coroutine_stack:
52 call_stack = coro_info.call_stack
53 internal_stack = [_format_stack_entry(frame) for frame in call_stack]
54 task_stacks[task_id] = internal_stack
56 # Add the awaited_by relationships (external dependencies)
57 if task_info.awaited_by:
58 for coro_info in task_info.awaited_by:
59 call_stack = coro_info.call_stack
60 parent_task_id = coro_info.task_name
61 stack = [_format_stack_entry(frame) for frame in call_stack]
62 awaits.append((parent_task_id, stack, task_id))
63 return id2name, awaits, task_stacks
66def _build_tree(id2name, awaits, task_stacks):
67 id2label = {(NodeType.TASK, tid): name for tid, name in id2name.items()}
68 children = defaultdict(list)
69 cor_nodes = defaultdict(dict) # Maps parent -> {frame_name: node_key}
70 next_cor_id = count(1)
72 def get_or_create_cor_node(parent, frame):
73 """Get existing coroutine node or create new one under parent"""
74 if frame in cor_nodes[parent]:
75 return cor_nodes[parent][frame]
77 node_key = (NodeType.COROUTINE, f"c{next(next_cor_id)}")
78 id2label[node_key] = frame
79 children[parent].append(node_key)
80 cor_nodes[parent][frame] = node_key
81 return node_key
83 # Build task dependency tree with coroutine frames
84 for parent_id, stack, child_id in awaits:
85 cur = (NodeType.TASK, parent_id)
86 for frame in reversed(stack):
87 cur = get_or_create_cor_node(cur, frame)
89 child_key = (NodeType.TASK, child_id)
90 if child_key not in children[cur]: 90 ↛ 84line 90 didn't jump to line 84 because the condition on line 90 was always true
91 children[cur].append(child_key)
93 # Add coroutine stacks for leaf tasks
94 awaiting_tasks = {parent_id for parent_id, _, _ in awaits}
95 for task_id in id2name:
96 if task_id not in awaiting_tasks and task_id in task_stacks:
97 cur = (NodeType.TASK, task_id)
98 for frame in reversed(task_stacks[task_id]):
99 cur = get_or_create_cor_node(cur, frame)
101 return id2label, children
104def _roots(id2label, children):
105 all_children = {c for kids in children.values() for c in kids}
106 return [n for n in id2label if n not in all_children]
108# ─── detect cycles in the task-to-task graph ───────────────────────
109def _task_graph(awaits):
110 """Return {parent_task_id: {child_task_id, …}, …}."""
111 g = defaultdict(set)
112 for parent_id, _stack, child_id in awaits:
113 g[parent_id].add(child_id)
114 return g
117def _find_cycles(graph):
118 """
119 Depth-first search for back-edges.
121 Returns a list of cycles (each cycle is a list of task-ids) or an
122 empty list if the graph is acyclic.
123 """
124 WHITE, GREY, BLACK = 0, 1, 2
125 color = defaultdict(lambda: WHITE)
126 path, cycles = [], []
128 def dfs(v):
129 color[v] = GREY
130 path.append(v)
131 stack = [(v, iter(graph.get(v, ())))]
132 while stack:
133 node, children = stack[-1]
134 for w in children:
135 if color[w] == WHITE:
136 color[w] = GREY
137 path.append(w)
138 stack.append((w, iter(graph.get(w, ()))))
139 break
140 elif color[w] == GREY: # back-edge → cycle!
141 i = path.index(w)
142 cycles.append(path[i:] + [w]) # make a copy
143 else:
144 color[node] = BLACK
145 path.pop()
146 stack.pop()
148 for v in list(graph):
149 if color[v] == WHITE:
150 dfs(v)
151 return cycles
154# ─── PRINT TREE FUNCTION ───────────────────────────────────────
155def get_all_awaited_by(pid):
156 unwinder = RemoteUnwinder(pid)
157 return unwinder.get_all_awaited_by()
160def build_async_tree(result, task_emoji="(T)", cor_emoji=""):
161 """
162 Build a list of strings for pretty-print an async call tree.
164 The call tree is produced by `get_all_async_stacks()`, prefixing tasks
165 with `task_emoji` and coroutine frames with `cor_emoji`.
166 """
167 id2name, awaits, task_stacks = _index(result)
168 g = _task_graph(awaits)
169 cycles = _find_cycles(g)
170 if cycles:
171 raise CycleFoundException(cycles, id2name)
172 labels, children = _build_tree(id2name, awaits, task_stacks)
174 def pretty(node):
175 flag = task_emoji if node[0] == NodeType.TASK else cor_emoji
176 return f"{flag} {labels[node]}"
178 def render(root):
179 buf = []
180 stack = [(root, "", True)]
181 while stack:
182 node, prefix, last = stack.pop()
183 buf.append(f"{prefix}{'└── ' if last else '├── '}{pretty(node)}")
184 new_pref = prefix + (" " if last else "│ ")
185 kids = children.get(node, [])
186 for i in range(len(kids) - 1, -1, -1):
187 stack.append((kids[i], new_pref, i == len(kids) - 1))
188 return buf
190 return [render(root) for root in _roots(labels, children)]
193def build_task_table(result):
194 id2name, _, _ = _index(result)
195 table = []
197 for awaited_info in result:
198 thread_id = awaited_info.thread_id
199 for task_info in awaited_info.awaited_by:
200 # Get task info
201 task_id = task_info.task_id
202 task_name = task_info.task_name
204 # Build coroutine stack string
205 frames = [frame for coro in task_info.coroutine_stack
206 for frame in coro.call_stack]
207 coro_stack = " -> ".join(x.funcname for x in frames)
209 # Handle tasks with no awaiters
210 if not task_info.awaited_by:
211 table.append([thread_id, hex(task_id), task_name, coro_stack,
212 "", "", "0x0"])
213 continue
215 # Handle tasks with awaiters
216 for coro_info in task_info.awaited_by:
217 parent_id = coro_info.task_name
218 awaiter_frames = [x.funcname for x in coro_info.call_stack]
219 awaiter_chain = " -> ".join(awaiter_frames)
220 awaiter_name = id2name.get(parent_id, "Unknown")
221 parent_id_str = (hex(parent_id) if isinstance(parent_id, int)
222 else str(parent_id))
224 table.append([thread_id, hex(task_id), task_name, coro_stack,
225 awaiter_chain, awaiter_name, parent_id_str])
227 return table
229def _print_cycle_exception(exception: CycleFoundException):
230 print("ERROR: await-graph contains cycles - cannot print a tree!", file=sys.stderr)
231 print("", file=sys.stderr)
232 for c in exception.cycles:
233 inames = " → ".join(exception.id2name.get(tid, hex(tid)) for tid in c)
234 print(f"cycle: {inames}", file=sys.stderr)
237def exit_with_permission_help_text():
238 """
239 Prints a message pointing to platform-specific permission help text and exits the program.
240 This function is called when a PermissionError is encountered while trying
241 to attach to a process.
242 """
243 print(
244 "Error: The specified process cannot be attached to due to insufficient permissions.\n"
245 "See the Python documentation for details on required privileges and troubleshooting:\n"
246 "https://docs.python.org/3/howto/remote_debugging.html#permission-requirements\n",
247 file=sys.stderr,
248 )
249 sys.exit(1)
252_TRANSIENT_ERRORS = (RuntimeError, OSError, UnicodeDecodeError, MemoryError)
255def _get_awaited_by_tasks(pid: int, retries: int = 3) -> list:
256 for attempt in range(retries + 1):
257 try:
258 return get_all_awaited_by(pid)
259 except PermissionError:
260 exit_with_permission_help_text()
261 except ProcessLookupError:
262 print(f"Error: process {pid} not found.", file=sys.stderr)
263 sys.exit(1)
264 except _TRANSIENT_ERRORS as e:
265 if attempt < retries:
266 continue
267 if isinstance(e, RuntimeError):
268 while e.__context__ is not None:
269 e = e.__context__
270 print(f"Error retrieving tasks: {e}", file=sys.stderr)
271 sys.exit(1)
274def display_awaited_by_tasks_table(pid: int, retries: int = 3) -> None:
275 """Build and print a table of all pending tasks under `pid`."""
277 tasks = _get_awaited_by_tasks(pid, retries=retries)
278 table = build_task_table(tasks)
279 # Print the table in a simple tabular format
280 print(
281 f"{'tid':<10} {'task id':<20} {'task name':<20} {'coroutine stack':<50} {'awaiter chain':<50} {'awaiter name':<15} {'awaiter id':<15}"
282 )
283 print("-" * 180)
284 for row in table:
285 print(f"{row[0]:<10} {row[1]:<20} {row[2]:<20} {row[3]:<50} {row[4]:<50} {row[5]:<15} {row[6]:<15}")
288def display_awaited_by_tasks_tree(pid: int, retries: int = 3) -> None:
289 """Build and print a tree of all pending tasks under `pid`."""
291 tasks = _get_awaited_by_tasks(pid, retries=retries)
292 try:
293 result = build_async_tree(tasks)
294 except CycleFoundException as e:
295 _print_cycle_exception(e)
296 sys.exit(1)
298 for tree in result:
299 print("\n".join(tree))