Call Graph Introspection

Quellcode: Lib/asyncio/graph.py

---

asyncio bietet leistungsstarke Laufzeit-Introspektionswerkzeuge für Aufrufdiagramme, um den gesamten Aufrufgraph einer laufenden Coroutine oder eines Tasks oder eines suspendierten Futures zu verfolgen. Diese Werkzeuge und die zugrunde liegende Maschinerie können sowohl innerhalb eines Python-Programms als auch von externen Profilern und Debuggern verwendet werden.

Hinzugefügt in Version 3.14.

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

Gibt den asynchronen Aufrufgraph für den aktuellen Task oder den bereitgestellten Task oder Future aus.

Diese Funktion gibt Einträge aus, beginnend vom obersten Frame abwärts in Richtung des Aufrufpunktes.

Die Funktion erhält ein optionales Argument future. Wenn dieses nicht übergeben wird, wird der aktuell laufende Task verwendet.

Wenn die Funktion für den aktuellen Task aufgerufen wird, kann das optionale schlüsselwortgebundene Argument depth verwendet werden, um die angegebene Anzahl von Frames vom oberen Ende des Stacks zu überspringen.

Wenn das optionale schlüsselwortgebundene Argument limit angegeben wird, wird jeder Aufrufstack im resultierenden Graphen auf maximal abs(limit) Einträge gekürzt. Wenn limit positiv ist, bleiben die Einträge am nächsten zum Aufrufpunkt erhalten. Wenn limit negativ ist, bleiben die obersten Einträge erhalten. Wenn limit weggelassen wird oder None ist, sind alle Einträge vorhanden. Wenn limit gleich 0 ist, wird der Aufrufstack überhaupt nicht gedruckt, es werden nur "awaited by"-Informationen ausgegeben.

Wenn file weggelassen wird oder None ist, druckt die Funktion nach sys.stdout.

Beispiel

Der folgende Python-Code

import asyncio

async def test():
    asyncio.print_call_graph()

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

asyncio.run(main())

wird ausgeben

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

Ähnlich wie print_call_graph(), gibt aber einen String zurück. Wenn future None ist und kein aktueller Task vorhanden ist, gibt die Funktion einen leeren String zurück.

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

Erfasst den asynchronen Aufrufgraph für den aktuellen Task oder den bereitgestellten Task oder Future.

Die Funktion erhält ein optionales Argument future. Wenn dieses nicht übergeben wird, wird der aktuell laufende Task verwendet. Wenn kein aktueller Task vorhanden ist, gibt die Funktion None zurück.

Wenn die Funktion für den aktuellen Task aufgerufen wird, kann das optionale schlüsselwortgebundene Argument depth verwendet werden, um die angegebene Anzahl von Frames vom oberen Ende des Stacks zu überspringen.

Gibt ein FutureCallGraph Datenklassenobjekt zurück

• FutureCallGraph(future, call_stack, awaited_by)

  Wobei future eine Referenz auf ein Future oder einen Task (oder deren Unterklassen) ist.

  call_stack ist ein Tupel von FrameCallGraphEntry Objekten.

  awaited_by ist ein Tupel von FutureCallGraph Objekten.

• FrameCallGraphEntry(frame)

  Wobei frame ein Frame-Objekt einer regulären Python-Funktion im Aufrufstack ist.

Low-Level-Hilfsfunktionen

Um einen asynchronen Aufrufgraph zu introspektieren, benötigt asyncio die Kooperation von Kontrollflussstrukturen wie shield() oder TaskGroup. Jedes Mal, wenn ein zwischengeschaltetes Future Objekt mit Low-Level-APIs wie Future.add_done_callback() beteiligt ist, sollten die folgenden beiden Funktionen verwendet werden, um asyncio darüber zu informieren, wie genau solche zwischengeschalteten Future-Objekte mit den von ihnen umschlossenen oder gesteuerten Tasks verbunden sind.

asyncio.future_add_to_awaited_by(future, waiter, /)

Zeichnet auf, dass future von waiter erwartet wird.

Sowohl future als auch waiter müssen Instanzen von Future oder Task oder deren Unterklassen sein, andernfalls hat der Aufruf keine Auswirkung.

Ein Aufruf von future_add_to_awaited_by() muss von einem späteren Aufruf der Funktion future_discard_from_awaited_by() mit denselben Argumenten gefolgt werden.

asyncio.future_discard_from_awaited_by(future, waiter, /)

Zeichnet auf, dass future nicht mehr von waiter erwartet wird.

Sowohl future als auch waiter müssen Instanzen von Future oder Task oder deren Unterklassen sein, andernfalls hat der Aufruf keine Auswirkung.