Call Graph Introspection

原始碼：Lib/asyncio/graph.py

asyncio has powerful runtime call graph introspection utilitiesto trace the entire call graph of a runningcoroutine ortask, ora suspendedfuture. These utilities and the underlying machinerycan be used from within a Python program or by external profilersand debuggers.

在 3.14 版被加入.

asyncio.print_call_graph(future=None,/,*,file=None,depth=1,limit=None)

Print the async call graph for the current task or the providedTask orFuture.

This function prints entries starting from the top frame and goingdown towards the invocation point.

The function receives an optionalfuture argument.If not passed, the current running task will be used.

If the function is called onthe current task, the optionalkeyword-onlydepth argument can be used to skip the specifiednumber of frames from top of the stack.

If the optional keyword-onlylimit argument is provided, each call stackin the resulting graph is truncated to include at mostabs(limit)entries. Iflimit is positive, the entries left are the closest tothe invocation point. Iflimit is negative, the topmost entries areleft. Iflimit is omitted orNone, all entries are present.Iflimit is0, the call stack is not printed at all, only"awaited by" information is printed.

Iffile is omitted orNone, the function will printtosys.stdout.

範例：

以下 Python 程式碼：

importasyncioasyncdeftest():asyncio.print_call_graph()asyncdefmain():asyncwithasyncio.TaskGroup()asg:g.create_task(test(),name='test')asyncio.run(main())

會印出：

*Task(name='test',id=0x1039f0fe0)+Callstack:|File't2.py',line4,inasynctest()+Awaitedby:*Task(name='Task-1',id=0x103a5e060)+Callstack:|File'taskgroups.py',line107,inasyncTaskGroup.__aexit__()|File't2.py',line7,inasyncmain()
asyncio.format_call_graph(future=None,/,*,depth=1,limit=None)

Likeprint_call_graph(), but returns a string.Iffuture isNone and there's no current task,the function returns an empty string.

asyncio.capture_call_graph(future=None,/,*,depth=1,limit=None)

Capture the async call graph for the current task or the providedTask orFuture.

The function receives an optionalfuture argument.If not passed, the current running task will be used. If there's nocurrent task, the function returnsNone.

If the function is called onthe current task, the optionalkeyword-onlydepth argument can be used to skip the specifiednumber of frames from top of the stack.

會回傳一個FutureCallGraph 資料類別物件：

  • FutureCallGraph(future,call_stack,awaited_by)

    Wherefuture is a reference to aFuture oraTask (or their subclasses.)

    call_stack 是一個由FrameCallGraphEntry 物件組成的元組。

    awaited_by 是一個由FutureCallGraph 物件組成的元組。

  • FrameCallGraphEntry(frame)

    Whereframe is a frame object of a regular Python functionin the call stack.

低階工具函式

To introspect an async call graph asyncio requires cooperation fromcontrol flow structures, such asshield() orTaskGroup.Any time an intermediateFuture object with low-level APIs likeFuture.add_done_callback() isinvolved, the following two functions should be used to inform asyncioabout how exactly such intermediate future objects are connected withthe tasks they wrap or control.

asyncio.future_add_to_awaited_by(future,waiter,/)

Record thatfuture is awaited on bywaiter.

Bothfuture andwaiter must be instances ofFuture orTask or their subclasses,otherwise the call would have no effect.

A call tofuture_add_to_awaited_by() must be followed by aneventual call to thefuture_discard_from_awaited_by() functionwith the same arguments.

asyncio.future_discard_from_awaited_by(future,waiter,/)

Record thatfuture is no longer awaited on bywaiter.

Bothfuture andwaiter must be instances ofFuture orTask or their subclasses, otherwisethe call would have no effect.