# 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.