asyncio — planificator de I/O asincron

Acest modul oferă un planificator cu multitasking cooperativ pentru corutinele async/await, împreună cu primitive pentru sincronizare (lacăte, evenimente) și lucru în rețea TCP neblocant prin cititoare și scriitoare de fluxuri. Sarcinile sunt rulate concurent pe o singură buclă de evenimente; sarcina aflată în curs de execuție cedează controlul înapoi buclei prin await.

Exemplu:

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

Funcții de bază

asyncio.create_task(coro: Coroutine) → Task

Creează o sarcină nouă din corutina dată și o planifică pentru execuție.

Returnează obiectul Task corespunzător.

asyncio.current_task() → Task

Returnează obiectul Task asociat sarcinii aflate în curs de execuție.

asyncio.run(coro: Coroutine) → Any

Creează o sarcină nouă din corutina dată și o rulează până la finalizare.

Returnează valoarea returnată de coro.

asyncio.sleep(t: float) → None

Adoarme timp de t secunde (poate fi un float).

Aceasta este o corutină.

asyncio.sleep_ms(t: int) → None

Adoarme timp de t milisecunde.

Aceasta este o corutină și o extensie MicroPython.

Funcții suplimentare

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

Așteaptă finalizarea obiectului awaitable, dar îl anulează dacă durează mai mult de timeout secunde. Dacă awaitable nu este o sarcină, atunci din el va fi creată o sarcină.

Dacă survine un timeout, sarcina este anulată și se ridică asyncio.TimeoutError: acesta ar trebui interceptat de apelant. Sarcina primește asyncio.CancelledError, care poate fi ignorat sau interceptat folosind try...except sau try...finally pentru a rula cod de curățare.

Returnează valoarea de retur a lui awaitable.

Aceasta este o corutină.

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

Similar cu wait_for(), dar timeout este un întreg exprimat în milisecunde.

Aceasta este o corutină și o extensie MicroPython.

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

Rulează concurent toate obiectele awaitables. Orice awaitables care nu sunt sarcini sunt promovate la sarcini.

Returnează o listă cu valorile de retur ale tuturor obiectelor awaitables.

Aceasta este o corutină.

class Task

class asyncio.Task

Acest obiect împachetează o corutină într-o sarcină în curs de execuție. Sarcinile pot fi așteptate folosind await task, ceea ce va aștepta finalizarea sarcinii și va returna valoarea de retur a sarcinii.

Sarcinile nu ar trebui create direct, ci mai degrabă folosind create_task() pentru a le crea.

cancel() → None

Anulează sarcina prin injectarea în ea a asyncio.CancelledError. Sarcina poate ignora această excepție. Codul de curățare poate fi rulat prin interceptarea ei sau prin try ... finally.

class Event

class asyncio.Event

Creează un eveniment nou care poate fi folosit pentru sincronizarea sarcinilor. Evenimentele pornesc în starea ștearsă.

is_set() → bool

Returnează True dacă evenimentul este setat, False în caz contrar.

set() → None

Setează evenimentul. Orice sarcini care așteaptă evenimentul vor fi planificate pentru execuție.

Notă: aceasta trebuie apelată din interiorul unei sarcini. Nu este sigur să fie apelată dintr-o IRQ, dintr-o funcție de retroapelare (callback) a planificatorului sau din alt fir de execuție. Vezi ThreadSafeFlag.

clear() → None

Șterge evenimentul.

wait() → None

Așteaptă ca evenimentul să fie setat. Dacă evenimentul este deja setat, atunci revine imediat.

Aceasta este o corutină.

class ThreadSafeFlag

class asyncio.ThreadSafeFlag

Creează un fanion nou care poate fi folosit pentru sincronizarea unei sarcini cu cod care rulează în afara buclei asyncio, cum ar fi alte fire de execuție, IRQ-uri sau funcții de retroapelare (callback) ale planificatorului. Fanioanele pornesc în starea ștearsă.

set() → None

Setează fanionul. Dacă există o sarcină care așteaptă fanionul, aceasta va fi planificată pentru execuție.

clear() → None

Șterge fanionul. Acest lucru poate fi folosit pentru a asigura că un fanion posibil setat anterior este șters înainte de a-l aștepta.

wait() → None

Așteaptă ca fanionul să fie setat. Dacă fanionul este deja setat, atunci revine imediat. Fanionul este resetat automat la revenirea din wait.

Un fanion poate fi așteptat doar de o singură sarcină la un moment dat.

Aceasta este o corutină.

class Lock

class asyncio.Lock

Creează un lacăt nou care poate fi folosit pentru coordonarea sarcinilor. Lacătele pornesc în starea deblocată.

Pe lângă metodele de mai jos, lacătele pot fi folosite într-o instrucțiune async with.

locked() → bool

Returnează True dacă lacătul este blocat, altfel False.

acquire() → bool

Așteaptă ca lacătul să fie în starea deblocată și apoi îl blochează în mod atomic. Doar o singură sarcină poate dobândi lacătul la un moment dat.

Aceasta este o corutină.

release() → None

Eliberează lacătul. Dacă există sarcini care așteaptă lacătul, atunci următoarea din coadă este planificată pentru execuție, iar lacătul rămâne blocat. În caz contrar, nu există sarcini în așteptare și lacătul devine deblocat.

Conexiuni de flux TCP

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

Deschide o conexiune TCP către host și port date. Adresa host va fi rezolvată folosind socket.getaddrinfo(), care în prezent este un apel blocant. Dacă ssl este un obiect ssl.SSLContext, acest context este folosit pentru a crea transportul; dacă ssl este True, este folosit un context implicit.

Returnează o pereche de fluxuri: un flux cititor și un flux scriitor. Va ridica o eroare OSError specifică socket-ului dacă gazda nu a putut fi rezolvată sau dacă conexiunea nu a putut fi stabilită.

Aceasta este o corutină.

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

Pornește un server TCP pe host și port date. Funcția callback va fi apelată pentru conexiunile primite și acceptate și i se vor transmite 2 argumente: fluxurile cititor și scriitor pentru conexiune.

Dacă ssl este un obiect ssl.SSLContext, acest context este folosit pentru a crea transportul.

Returnează un obiect Server.

Aceasta este o corutină.

class asyncio.Stream

Aceasta reprezintă o conexiune de flux TCP. Pentru a minimiza codul, această clasă implementează atât un cititor, cât și un scriitor, iar atât StreamReader, cât și StreamWriter sunt alias pentru această clasă.

get_extra_info(v: str) → Any

Obține informații suplimentare despre flux, date de v. Valorile valide pentru v sunt: peername.

close() → None

Închide fluxul.

wait_closed() → None

Așteaptă ca fluxul să se închidă.

Aceasta este o corutină.

read(n: int = -1) → bytes

Citește până la n octeți și îi returnează. Dacă n nu este furnizat sau este -1, atunci citește toți octeții până la EOF. Valoarea returnată va fi un obiect bytes gol dacă EOF este întâlnit înainte de citirea oricăror octeți.

Aceasta este o corutină.

readinto(buf: bytearray | memoryview) → int

Citește până la n octeți în buf, n fiind egal cu lungimea lui buf.

Returnează numărul de octeți citiți în buf.

Aceasta este o corutină și o extensie MicroPython.

readexactly(n: int) → bytes

Citește exact n octeți și îi returnează ca obiect bytes.

Ridică o excepție EOFError dacă fluxul se termină înainte de citirea a n octeți.

Aceasta este o corutină.

readline() → bytes

Citește o linie și o returnează.

Aceasta este o corutină.

write(buf: bytes) → None

Acumulează buf în tamponul de ieșire. Datele sunt golite doar atunci când este apelat Stream.drain(). Se recomandă apelarea Stream.drain() imediat după apelarea acestei funcții.

drain() → None

Golește (scrie) toate datele de ieșire stocate în tampon către flux.

Aceasta este o corutină.

class asyncio.Server

Aceasta reprezintă clasa server returnată de start_server(). Poate fi folosită într-o instrucțiune async with pentru a închide serverul la ieșire.

close() → None

Închide serverul.

wait_closed() → None

Așteaptă ca serverul să se închidă.

Aceasta este o corutină.

Bucla de evenimente

asyncio.get_event_loop() → Loop

Returnează bucla de evenimente folosită pentru planificarea și rularea sarcinilor. Vezi Loop.

asyncio.new_event_loop() → Loop

Resetează bucla de evenimente și o returnează.

Notă: deoarece MicroPython are doar o singură buclă de evenimente, această funcție doar resetează starea buclei, nu creează una nouă.

class asyncio.Loop

Aceasta reprezintă obiectul care planifică și rulează sarcinile. Nu poate fi creat; folosiți în schimb get_event_loop().

create_task(coro: Coroutine) → Task

Creează o sarcină din coro dat și returnează noul obiect Task.

run_forever() → None

Rulează bucla de evenimente până când este apelat stop().

run_until_complete(awaitable: Awaitable) → Any

Rulează obiectul awaitable dat până la finalizare. Dacă awaitable nu este o sarcină, atunci va fi promovat la una.

stop() → None

Oprește bucla de evenimente.

close() → None

Închide bucla de evenimente.

set_exception_handler(handler: Callable) → None

Setează gestionarul de excepții care va fi apelat atunci când o sarcină ridică o excepție neinterceptată. handler ar trebui să accepte două argumente: (loop, context).

get_exception_handler() → Callable | None

Obține gestionarul de excepții curent. Returnează gestionarul sau None dacă nu este setat niciun gestionar personalizat.

default_exception_handler(context: dict) → None

Gestionarul de excepții implicit care este apelat.

call_exception_handler(context: dict) → None

Apelează gestionarul de excepții curent. Argumentul context este transmis mai departe și este un dicționar care conține cheile: 'message', 'exception', 'future'.