Introspektion av anropsgrafen

Källkod: Lib/asyncio/graph.py


asyncio har kraftfulla verktyg för introspektion av anropsgrafen under körning för att spåra hela anropsgrafen för en körande coroutine eller task, eller en suspenderad future. Dessa verktyg och det underliggande maskineriet kan användas inifrån ett Python-program eller av externa profilerare och debuggers.

Tillagd i version 3.14.

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

Skriv ut grafen för asynkrona anrop för den aktuella uppgiften eller den angivna Task eller Future.

Denna funktion skriver ut poster med början från den övre ramen och nedåt mot anropspunkten.

Funktionen tar emot ett valfritt future-argument. Om det inte skickas med kommer den aktuella körningen att användas.

Om funktionen anropas på den aktuella uppgiften kan det valfria argumentet depth, som endast innehåller nyckelord, användas för att hoppa över det angivna antalet bildrutor från toppen av stacken.

Om det valfria argumentet limit, som endast innehåller nyckelord, anges, trunkeras varje anropsstack i den resulterande grafen så att den innehåller högst abs(limit) poster. Om limit är positiv, är de poster som lämnas kvar de som ligger närmast anropspunkten. Om limit är negativ, lämnas de översta posterna. Om limit utelämnas eller är None finns alla poster kvar. Om limit är 0 skrivs inte anropsstacken ut alls, endast ”awaited by”-information skrivs ut.

Om file utelämnas eller None, kommer funktionen att skriva ut till sys.stdout.

Exempel:

Följande Python-kod:

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

kommer att skriva ut:

* Uppgift(name='test', id=0x1039f0fe0)
+ Anropsstack:
| Fil 't2.py', rad 4, i async test()
+ Väntas av:
   * Task(name='Task-1', id=0x103a5e060)
      + Anropsstack:
      | Fil 'taskgroups.py', rad 107, i async TaskGroup.__aexit__()
      | Fil 't2.py', rad 7, i async main()
asyncio.format_call_graph(future=None, /, *, depth=1, limit=None)

Som print_call_graph(), men returnerar en sträng. Om future är None och det inte finns någon aktuell uppgift, returnerar funktionen en tom sträng.

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

Fångar async-anropsgrafen för den aktuella uppgiften eller den angivna Task eller Future.

Funktionen tar emot ett valfritt future-argument. Om det inte skickas med kommer den aktuella körningen att användas. Om det inte finns någon aktuell uppgift returnerar funktionen None.

Om funktionen anropas på den aktuella uppgiften kan det valfria argumentet depth, som endast innehåller nyckelord, användas för att hoppa över det angivna antalet bildrutor från toppen av stacken.

Returnerar ett dataklassobjekt av typen FutureCallGraph:

  • FutureCallGraph(framtid, call_stack, väntat_by)

    Där future är en referens till en Future eller en Task (eller deras underklasser.)

    call_stack är en tupel av FrameCallGraphEntry objekt.

    awaited_by är en tupel av FutureCallGraph objekt.

  • FrameCallGraphEntry(ram)

    Där frame är ett frame-objekt för en vanlig Python-funktion i anropsstacken.

Nyttofunktioner på låg nivå

För att introspektera en asynkron anropsgraf kräver asyncio samarbete från kontrollflödesstrukturer, såsom shield() eller TaskGroup. Varje gång ett mellanliggande Future-objekt med lågnivå-API:er som Future.add_done_callback() är inblandat, bör följande två funktioner användas för att informera asyncio om exakt hur sådana mellanliggande future-objekt är kopplade till de uppgifter de omsluter eller kontrollerar.

asyncio.future_add_to_awaited_by(future, waiter, /)

Registrera att framtiden inväntas av vaktmästaren.

Både future och waiter måste vara instanser av Future eller Task eller deras subklasser, annars har anropet ingen effekt.

Ett anrop till future_add_to_awaited_by() måste följas av ett eventuellt anrop till funktionen future_discard_from_awaited_by() med samma argument.

asyncio.future_discard_from_awaited_by(future, waiter, /)

Registrera att framtiden inte längre inväntas av vaktmästaren.

Både future och waiter måste vara instanser av Future eller Task eller deras subklasser, annars har anropet ingen effekt.