Introspeção do grafo de chamadas

Código-fonte: Lib/asyncio/grafo.py

---

O asyncio disponibiliza utilitários poderosos de introspeção do grafo de chamadas em tempo de execução, que permitem traçar o grafo de chamadas completo de uma corrotina ou tarefa em execução, ou de um futuro suspenso. Estes utilitários e a respectiva maquinaria subjacente podem ser utilizados em um programa Python ou por perfis externos e depuradores.

Adicionado na versão 3.14.

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

Exibe o grafo de chamadas assíncronas para a tarefa atual ou para a Task ou Future fornecida.

Esta função exibe as entradas a partir do quadro superior até ao ponto de invocação.

A função recebe um argumento opcional future. Se não for fornecido, será utilizada a tarefa em execução atual.

Se a função for chamada na tarefa atual, o argumento opcional somente-nomeado depth pode ser usado para ignorar o número especificado de quadros a partir do topo da pilha.

Se o argumento opcional somente-nomeado limit for fornecido, cada pilha de chamadas no gráfico resultante será truncada para incluir no máximo abs(limit) entradas. Se limit for positivo, as entradas exibidas serão as mais próximas do ponto de invocação. Se limit for negativo, as entradas mais altas são exibidas. Se limit for omitido ou None, todas as entradas são apresentadas. Se limit for 0, a pilha de chamadas não é exibida, apenas as informações “aguardadas por” são exibidas.

Se file for omitido ou for None, a saída da função será encaminhada para sys.stdout.

Exemplo:

O seguinte código Python:

import asyncioasync def test():    asyncio.print_call_graph()async def main():    async with asyncio.TaskGroup() as g:        g.create_task(test(), name='test')asyncio.run(main())

irá exibir:

* Task(name='test', id=0x1039f0fe0)+ Call stack:|   File 't2.py', line 4, in async test()+ Awaited by:   * Task(name='Task-1', id=0x103a5e060)      + Call stack:      |   File 'taskgroups.py', line 107, in async TaskGroup.__aexit__()      |   File 't2.py', line 7, in async main()

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

Semelhante a print_call_graph(), mas retorna uma string. Se future for None e não houver nenhuma tarefa atual, a função retorna uma string vazia.

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

Captura o grafo de chamadas assíncronas para a tarefa atual ou para a Task ou Future fornecida.

A função recebe um argumento opcional future. Se não for fornecido, será utilizada a tarefa em execução atual. Se não existir nenhuma tarefa atual, a função retorna None.

Se a função for chamada na tarefa atual, o argumento opcional somente-nomeado depth pode ser usado para ignorar o número especificado de quadros a partir do topo da pilha.

Retorna um objeto da classe de dados FutureCallGraph:

• FutureCallGraph(future, call_stack, awaited_by)

  Onde future é uma referência a um Future ou a uma Task (ou às suas subclasses).

  call_stack é uma tupla de objetos FrameCallGraphEntry.

  awaited_by é uma tupla de objetos FutureCallGraph.

• FrameCallGraphEntry(frame)

  Onde frame é um objeto de quadro de uma função Python regular na pilha de chamadas.

Funções utilitárias de baixo nível

Para efetuar a introspeção de um grafo de chamadas assíncronas, o asyncio requer a cooperação de estruturas de controle de fluxo, como shield() ou TaskGroup. Sempre que um objeto Future intermediário com APIs de baixo nível, como Future.add_done_callback(), estiver envolvido, as duas funções seguintes devem ser utilizadas para informar o asyncio sobre a forma como esses objetos future intermédios estão ligados às tarefas que envolvem ou controlam.

asyncio.future_add_to_awaited_by(future, waiter, /)

Registra que future está a ser aguardado por waiter.

Tanto future quanto waiter devem ser instâncias de Future ou Task ou de suas subclasses; caso contrário, a chamada não terá efeito.

Uma chamada a future_add_to_awaited_by() deve ser seguida por uma chamada eventual à função future_discard_from_awaited_by() com os mesmos argumentos.

asyncio.future_discard_from_awaited_by(future, waiter, /)

Registra que future não está mais sendo aguardado por waiter.

Tanto future quanto waiter devem ser instâncias de Future ou Task ou de suas subclasses; caso contrário, a chamada não terá efeito.