asyncio — asynchrone I/O-scheduler

Deze module biedt een coöperatieve multitasking-scheduler voor async/await-coroutines, samen met primitieven voor synchronisatie (locks, events) en niet-blokkerend TCP-netwerken via stream readers en writers. Taken worden gelijktijdig uitgevoerd op één enkele event loop; de momenteel uitgevoerde taak geeft de controle met await terug aan de loop.

Voorbeeld:

import asyncio

async def blink(led, period_ms):
    while True:
        led.on()
        await asyncio.sleep_ms(5)
        led.off()
        await asyncio.sleep_ms(period_ms)

async def main(led1, led2):
    asyncio.create_task(blink(led1, 700))
    asyncio.create_task(blink(led2, 400))
    await asyncio.sleep_ms(10_000)

# Running on an OpenMV Cam
from machine import LED
asyncio.run(main(LED(1), LED(2)))

Kernfuncties

asyncio.create_task(coro: Coroutine) → Task

Maak een nieuwe taak van de gegeven coroutine en plan deze om uitgevoerd te worden.

Retourneert het bijbehorende Task-object.

asyncio.current_task() → Task

Retourneert het Task-object dat is gekoppeld aan de momenteel uitgevoerde taak.

asyncio.run(coro: Coroutine) → Any

Maak een nieuwe taak van de gegeven coroutine en voer deze uit totdat ze voltooid is.

Retourneert de waarde die door coro wordt teruggegeven.

asyncio.sleep(t: float) → None

Slaap gedurende t seconden (kan een float zijn).

Dit is een coroutine.

asyncio.sleep_ms(t: int) → None

Slaap gedurende t milliseconden.

Dit is een coroutine en een MicroPython-uitbreiding.

Aanvullende functies

asyncio.wait_for(awaitable: Awaitable, timeout: float) → Any

Wacht totdat de awaitable voltooid is, maar annuleer deze als ze langer dan timeout seconden duurt. Als awaitable geen taak is, wordt er een taak van gemaakt.

Als er een timeout optreedt, wordt de taak geannuleerd en wordt asyncio.TimeoutError opgeworpen: dit moet door de aanroeper worden opgevangen. De taak ontvangt asyncio.CancelledError, die genegeerd kan worden of opgevangen kan worden met try...except of try...finally om opruimcode uit te voeren.

Retourneert de retourwaarde van awaitable.

Dit is een coroutine.

asyncio.wait_for_ms(awaitable: Awaitable, timeout: int) → Any

Vergelijkbaar met wait_for(), maar timeout is een geheel getal in milliseconden.

Dit is een coroutine en een MicroPython-uitbreiding.

asyncio.gather(*awaitables, return_exceptions: bool = False) → List

Voer alle awaitables gelijktijdig uit. Alle awaitables die geen taken zijn, worden tot taken bevorderd.

Retourneert een lijst met de retourwaarden van alle awaitables.

Dit is een coroutine.

class Task

class asyncio.Task

Dit object verpakt een coroutine in een uitgevoerde taak. Op taken kan worden gewacht met await task, wat wacht totdat de taak voltooid is en de retourwaarde van de taak teruggeeft.

Taken mogen niet rechtstreeks worden aangemaakt; gebruik in plaats daarvan create_task() om ze aan te maken.

cancel() → None

Annuleer de taak door er asyncio.CancelledError in te injecteren. De taak kan deze uitzondering negeren. Opruimcode kan worden uitgevoerd door deze op te vangen, of via try ... finally.

class Event

class asyncio.Event

Maak een nieuw event aan dat gebruikt kan worden om taken te synchroniseren. Events beginnen in de gewiste toestand.

is_set() → bool

Retourneert True als het event is ingesteld, anders False.

set() → None

Stel het event in. Alle taken die op het event wachten, worden gepland om uitgevoerd te worden.

Opmerking: dit moet vanuit een taak worden aangeroepen. Het is niet veilig om dit aan te roepen vanuit een IRQ, scheduler-callback of een andere thread. Zie ThreadSafeFlag.

clear() → None

Wis het event.

wait() → None

Wacht totdat het event is ingesteld. Als het event al is ingesteld, keert het onmiddellijk terug.

Dit is een coroutine.

class ThreadSafeFlag

class asyncio.ThreadSafeFlag

Maak een nieuwe vlag aan die gebruikt kan worden om een taak te synchroniseren met code die buiten de asyncio-loop draait, zoals andere threads, IRQ’s of scheduler-callbacks. Vlaggen beginnen in de gewiste toestand.

set() → None

Stel de vlag in. Als er een taak op de vlag wacht, wordt deze gepland om uitgevoerd te worden.

clear() → None

Wis de vlag. Dit kan gebruikt worden om ervoor te zorgen dat een mogelijk eerder ingestelde vlag gewist is voordat erop gewacht wordt.

wait() → None

Wacht totdat de vlag is ingesteld. Als de vlag al is ingesteld, keert het onmiddellijk terug. De vlag wordt automatisch teruggezet bij terugkeer uit wait.

Op een vlag kan slechts één taak tegelijk wachten.

Dit is een coroutine.

class Lock

class asyncio.Lock

Maak een nieuwe lock aan die gebruikt kan worden om taken te coördineren. Locks beginnen in de ontgrendelde toestand.

Naast de onderstaande methoden kunnen locks gebruikt worden in een async with-statement.

locked() → bool

Retourneert True als de lock vergrendeld is, anders False.

acquire() → bool

Wacht totdat de lock zich in de ontgrendelde toestand bevindt en vergrendel deze vervolgens op een atomaire manier. Slechts één taak kan de lock op enig moment verkrijgen.

Dit is een coroutine.

release() → None

Geef de lock vrij. Als er taken op de lock wachten, wordt de volgende in de wachtrij gepland om uitgevoerd te worden en blijft de lock vergrendeld. Anders wachten er geen taken en wordt de lock ontgrendeld.

TCP-streamverbindingen

asyncio.open_connection(host: str, port: int, ssl: ssl.SSLContext | bool | None = None) → Tuple[Stream, Stream]

Open een TCP-verbinding naar de gegeven host en port. Het host-adres wordt opgelost met socket.getaddrinfo(), wat momenteel een blokkerende aanroep is. Als ssl een ssl.SSLContext-object is, wordt deze context gebruikt om het transport aan te maken; als ssl True is, wordt een standaardcontext gebruikt.

Retourneert een paar streams: een reader- en een writer-stream. Werpt een socketspecifieke OSError op als de host niet opgelost kon worden of als de verbinding niet tot stand gebracht kon worden.

Dit is een coroutine.

asyncio.start_server(callback: Callable, host: str, port: int, backlog: int = 5, ssl: ssl.SSLContext | None = None) → Server

Start een TCP-server op de gegeven host en port. De callback wordt aangeroepen bij inkomende, geaccepteerde verbindingen en krijgt 2 argumenten doorgegeven: reader- en writer-streams voor de verbinding.

Als ssl een ssl.SSLContext-object is, wordt deze context gebruikt om het transport aan te maken.

Retourneert een Server-object.

Dit is een coroutine.

class asyncio.Stream

Dit vertegenwoordigt een TCP-streamverbinding. Om code te minimaliseren implementeert deze klasse zowel een reader als een writer, en zowel StreamReader als StreamWriter zijn aliassen voor deze klasse.

get_extra_info(v: str) → Any

Verkrijg extra informatie over de stream, gegeven door v. De geldige waarden voor v zijn: peername.

close() → None

Sluit de stream.

wait_closed() → None

Wacht totdat de stream gesloten is.

Dit is een coroutine.

read(n: int = -1) → bytes

Lees maximaal n bytes en retourneer deze. Als n niet wordt opgegeven of -1 is, lees dan alle bytes tot EOF. De geretourneerde waarde is een leeg bytes-object als EOF wordt aangetroffen voordat er bytes zijn gelezen.

Dit is een coroutine.

readinto(buf: bytearray | memoryview) → int

Lees maximaal n bytes in buf, waarbij n gelijk is aan de lengte van buf.

Retourneert het aantal bytes dat in buf is gelezen.

Dit is een coroutine en een MicroPython-uitbreiding.

readexactly(n: int) → bytes

Lees precies n bytes en retourneer deze als een bytes-object.

Werpt een EOFError-uitzondering op als de stream eindigt voordat n bytes zijn gelezen.

Dit is een coroutine.

readline() → bytes

Lees een regel en retourneer deze.

Dit is een coroutine.

write(buf: bytes) → None

Voeg buf toe aan de uitvoerbuffer. De data wordt pas weggeschreven wanneer Stream.drain() wordt aangeroepen. Het wordt aanbevolen om Stream.drain() onmiddellijk na het aanroepen van deze functie aan te roepen.

drain() → None

Schrijf (drain) alle gebufferde uitvoerdata weg naar de stream.

Dit is een coroutine.

class asyncio.Server

Dit vertegenwoordigt de serverklasse die door start_server() wordt geretourneerd. Deze kan gebruikt worden in een async with-statement om de server bij het verlaten te sluiten.

close() → None

Sluit de server.

wait_closed() → None

Wacht totdat de server gesloten is.

Dit is een coroutine.

Event Loop

asyncio.get_event_loop() → Loop

Retourneert de event loop die gebruikt wordt om taken te plannen en uit te voeren. Zie Loop.

asyncio.new_event_loop() → Loop

Zet de event loop terug en retourneer deze.

Opmerking: aangezien MicroPython slechts één enkele event loop heeft, zet deze functie alleen de toestand van de loop terug; er wordt geen nieuwe aangemaakt.

class asyncio.Loop

Dit vertegenwoordigt het object dat taken plant en uitvoert. Het kan niet aangemaakt worden; gebruik in plaats daarvan get_event_loop().

create_task(coro: Coroutine) → Task

Maak een taak van de gegeven coro en retourneer het nieuwe Task-object.

run_forever() → None

Voer de event loop uit totdat stop() wordt aangeroepen.

run_until_complete(awaitable: Awaitable) → Any

Voer de gegeven awaitable uit totdat deze voltooid is. Als awaitable geen taak is, wordt deze tot een taak bevorderd.

stop() → None

Stop de event loop.

close() → None

Sluit de event loop.

set_exception_handler(handler: Callable) → None

Stel de exception handler in die aangeroepen moet worden wanneer een taak een uitzondering opwerpt die niet wordt opgevangen. De handler moet twee argumenten accepteren: (loop, context).

get_exception_handler() → Callable | None

Verkrijg de huidige exception handler. Retourneert de handler, of None als er geen aangepaste handler is ingesteld.

default_exception_handler(context: dict) → None

De standaard exception handler die wordt aangeroepen.

call_exception_handler(context: dict) → None

Roep de huidige exception handler aan. Het argument context wordt doorgegeven en is een dictionary met de sleutels: 'message', 'exception', 'future'.