Debian Codegraph @

Doc/library/asyncio-graph.rst

raw
1 .. currentmodule:: asyncio
2
3
4 .. _asyncio-graph:
5
6 ========================
7 Call Graph Introspection
8 ========================
9
10 **Source code:** :source:`Lib/asyncio/graph.py`
11
12 -------------------------------------
13
14 asyncio has powerful runtime call graph introspection utilities
15 to trace the entire call graph of a running *coroutine* or *task*, or
16 a suspended *future*. These utilities and the underlying machinery
17 can be used from within a Python program or by external profilers
18 and debuggers.
19
20 .. versionadded:: 3.14
21
22
23 .. function:: print_call_graph(future=None, /, *, file=None, depth=1, limit=None)
24
25 Print the async call graph for the current task or the provided
26 :class:`Task` or :class:`Future`.
27
28 This function prints entries starting from the top frame and going
29 down towards the invocation point.
30
31 The function receives an optional *future* argument.
32 If not passed, the current running task will be used.
33
34 If the function is called on *the current task*, the optional
35 keyword-only *depth* argument can be used to skip the specified
36 number of frames from top of the stack.
37
38 If the optional keyword-only *limit* argument is provided, each call stack
39 in the resulting graph is truncated to include at most ``abs(limit)``
40 entries. If *limit* is positive, the entries left are the closest to
41 the invocation point. If *limit* is negative, the topmost entries are
42 left. If *limit* is omitted or ``None``, all entries are present.
43 If *limit* is ``0``, the call stack is not printed at all, only
44 "awaited by" information is printed.
45
46 If *file* is omitted or ``None``, the function will print
47 to :data:`sys.stdout`.
48
49 **Example:**
50
51 The following Python code:
52
53 .. code-block:: python
54
55 import asyncio
56
57 async def test():
58 asyncio.print_call_graph()
59
60 async def main():
61 async with asyncio.TaskGroup() as g:
62 g.create_task(test(), name='test')
63
64 asyncio.run(main())
65
66 will print::
67
68 * Task(name='test', id=0x1039f0fe0)
69 + Call stack:
70 | File 't2.py', line 4, in async test()
71 + Awaited by:
72 * Task(name='Task-1', id=0x103a5e060)
73 + Call stack:
74 | File 'taskgroups.py', line 107, in async TaskGroup.__aexit__()
75 | File 't2.py', line 7, in async main()
76
77 .. function:: format_call_graph(future=None, /, *, depth=1, limit=None)
78
79 Like :func:`print_call_graph`, but returns a string.
80 If *future* is ``None`` and there's no current task,
81 the function returns an empty string.
82
83
84 .. function:: capture_call_graph(future=None, /, *, depth=1, limit=None)
85
86 Capture the async call graph for the current task or the provided
87 :class:`Task` or :class:`Future`.
88
89 The function receives an optional *future* argument.
90 If not passed, the current running task will be used. If there's no
91 current task, the function returns ``None``.
92
93 If the function is called on *the current task*, the optional
94 keyword-only *depth* argument can be used to skip the specified
95 number of frames from top of the stack.
96
97 Returns a ``FutureCallGraph`` data class object:
98
99 * ``FutureCallGraph(future, call_stack, awaited_by)``
100
101 Where *future* is a reference to a :class:`Future` or
102 a :class:`Task` (or their subclasses.)
103
104 ``call_stack`` is a tuple of ``FrameCallGraphEntry`` objects.
105
106 ``awaited_by`` is a tuple of ``FutureCallGraph`` objects.
107
108 * ``FrameCallGraphEntry(frame)``
109
110 Where *frame* is a frame object of a regular Python function
111 in the call stack.
112
113
114 Low level utility functions
115 ===========================
116
117 To introspect an async call graph asyncio requires cooperation from
118 control flow structures, such as :func:`shield` or :class:`TaskGroup`.
119 Any time an intermediate :class:`Future` object with low-level APIs like
120 :meth:`Future.add_done_callback() <asyncio.Future.add_done_callback>` is
121 involved, the following two functions should be used to inform asyncio
122 about how exactly such intermediate future objects are connected with
123 the tasks they wrap or control.
124
125
126 .. function:: future_add_to_awaited_by(future, waiter, /)
127
128 Record that *future* is awaited on by *waiter*.
129
130 Both *future* and *waiter* must be instances of
131 :class:`Future` or :class:`Task` or their subclasses,
132 otherwise the call would have no effect.
133
134 A call to ``future_add_to_awaited_by()`` must be followed by an
135 eventual call to the :func:`future_discard_from_awaited_by` function
136 with the same arguments.
137
138
139 .. function:: future_discard_from_awaited_by(future, waiter, /)
140
141 Record that *future* is no longer awaited on by *waiter*.
142
143 Both *future* and *waiter* must be instances of
144 :class:`Future` or :class:`Task` or their subclasses, otherwise
145 the call would have no effect.