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

1"""Tools to analyze tasks running in asyncio programs.""" 

2 

3from collections import defaultdict 

4from itertools import count 

5from enum import Enum 

6import sys 

7from _remote_debugging import RemoteUnwinder, FrameInfo 

8 

9class NodeType(Enum): 

10 COROUTINE = 1 

11 TASK = 2 

12 

13 

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 

24 

25 

26 

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 

39 

40 

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 

48 

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 

55 

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 

64 

65 

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) 

71 

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] 

76 

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 

82 

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) 

88 

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) 

92 

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) 

100 

101 return id2label, children 

102 

103 

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] 

107 

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 

115 

116 

117def _find_cycles(graph): 

118 """ 

119 Depth-first search for back-edges. 

120 

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 = [], [] 

127 

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() 

147 

148 for v in list(graph): 

149 if color[v] == WHITE: 

150 dfs(v) 

151 return cycles 

152 

153 

154# ─── PRINT TREE FUNCTION ─────────────────────────────────────── 

155def get_all_awaited_by(pid): 

156 unwinder = RemoteUnwinder(pid) 

157 return unwinder.get_all_awaited_by() 

158 

159 

160def build_async_tree(result, task_emoji="(T)", cor_emoji=""): 

161 """ 

162 Build a list of strings for pretty-print an async call tree. 

163 

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) 

173 

174 def pretty(node): 

175 flag = task_emoji if node[0] == NodeType.TASK else cor_emoji 

176 return f"{flag} {labels[node]}" 

177 

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 

189 

190 return [render(root) for root in _roots(labels, children)] 

191 

192 

193def build_task_table(result): 

194 id2name, _, _ = _index(result) 

195 table = [] 

196 

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 

203 

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) 

208 

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 

214 

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)) 

223 

224 table.append([thread_id, hex(task_id), task_name, coro_stack, 

225 awaiter_chain, awaiter_name, parent_id_str]) 

226 

227 return table 

228 

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) 

235 

236 

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) 

250 

251 

252_TRANSIENT_ERRORS = (RuntimeError, OSError, UnicodeDecodeError, MemoryError) 

253 

254 

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) 

272 

273 

274def display_awaited_by_tasks_table(pid: int, retries: int = 3) -> None: 

275 """Build and print a table of all pending tasks under `pid`.""" 

276 

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}") 

286 

287 

288def display_awaited_by_tasks_tree(pid: int, retries: int = 3) -> None: 

289 """Build and print a tree of all pending tasks under `pid`.""" 

290 

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) 

297 

298 for tree in result: 

299 print("\n".join(tree))