`asyncio` — scheduler di I/O asincrono¶

Questo modulo fornisce uno scheduler a multitasking cooperativo per le coroutine async/await, insieme a primitive per la sincronizzazione (lock, eventi) e per il networking TCP non bloccante tramite reader e writer di stream. I task vengono eseguiti in modo concorrente su un singolo event loop; il task attualmente in esecuzione restituisce il controllo al loop con await.

Esempio:

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

Funzioni principali¶

asyncio.create_task(coro: Coroutine) → Task¶

Crea un nuovo task a partire dalla coroutine specificata e lo pianifica per l’esecuzione.

Restituisce il corrispondente oggetto Task.

asyncio.current_task() → Task¶: Restituisce l’oggetto Task associato al task attualmente in esecuzione.

asyncio.run(coro: Coroutine) → Any¶

Crea un nuovo task a partire dalla coroutine specificata e lo esegue fino al completamento.

Restituisce il valore restituito da coro.

asyncio.sleep(t: float) → None¶

Mette in pausa per t secondi (può essere un float).

Questa è una coroutine.

asyncio.sleep_ms(t: int) → None¶

Mette in pausa per t millisecondi.

Questa è una coroutine, oltre che un’estensione di MicroPython.

Funzioni aggiuntive¶

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

Attende il completamento di awaitable, ma lo annulla se richiede più di timeout secondi. Se awaitable non è un task, ne verrà creato uno a partire da esso.

Se si verifica un timeout, il task viene annullato e viene sollevata l’eccezione asyncio.TimeoutError: questa dovrebbe essere intercettata dal chiamante. Il task riceve asyncio.CancelledError, che può essere ignorata oppure intercettata usando try...except o try...finally per eseguire codice di pulizia.

Restituisce il valore restituito da awaitable.

Questa è una coroutine.

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

Simile a wait_for(), ma timeout è un intero in millisecondi.

Questa è una coroutine, oltre che un’estensione di MicroPython.

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

Esegue tutti gli awaitables in modo concorrente. Tutti gli awaitables che non sono task vengono promossi a task.

Restituisce un elenco dei valori restituiti da tutti gli awaitables.

Questa è una coroutine.

class Task¶

class asyncio.Task¶

Questo oggetto incapsula una coroutine in un task in esecuzione. È possibile attendere i task usando await task, che attenderà il completamento del task e restituirà il valore restituito dal task stesso.

I task non dovrebbero essere creati direttamente; è preferibile usare create_task() per crearli.

cancel() → None¶: Annulla il task iniettando in esso asyncio.CancelledError. Il task può ignorare questa eccezione. È possibile eseguire codice di pulizia intercettandola, oppure tramite try ... finally.

class Event¶

class asyncio.Event¶

Crea un nuovo evento che può essere usato per sincronizzare i task. Gli eventi partono nello stato azzerato.

is_set() → bool¶: Restituisce True se l’evento è impostato, False altrimenti.

set() → None¶

Imposta l’evento. Tutti i task in attesa dell’evento verranno pianificati per l’esecuzione.

Nota: questo metodo deve essere chiamato dall’interno di un task. Non è sicuro chiamarlo da un IRQ, da una callback dello scheduler o da un altro thread. Vedi ThreadSafeFlag.

clear() → None¶: Azzera l’evento.

wait() → None¶

Attende che l’evento venga impostato. Se l’evento è già impostato, restituisce immediatamente.

Questa è una coroutine.

class ThreadSafeFlag¶

class asyncio.ThreadSafeFlag¶

Crea un nuovo flag che può essere usato per sincronizzare un task con codice in esecuzione al di fuori del loop asyncio, come altri thread, IRQ o callback dello scheduler. I flag partono nello stato azzerato.

set() → None¶: Imposta il flag. Se c’è un task in attesa del flag, questo verrà pianificato per l’esecuzione.

clear() → None¶: Azzera il flag. Questo può essere usato per assicurarsi che un flag eventualmente impostato in precedenza sia azzerato prima di metterlo in attesa.

wait() → None¶

Attende che il flag venga impostato. Se il flag è già impostato, restituisce immediatamente. Il flag viene automaticamente resettato al ritorno da wait.

Un flag può essere atteso solo da un singolo task alla volta.

Questa è una coroutine.

class Lock¶

class asyncio.Lock¶

Crea un nuovo lock che può essere usato per coordinare i task. I lock partono nello stato sbloccato.

Oltre ai metodi descritti di seguito, i lock possono essere usati in un’istruzione async with.

locked() → bool¶: Restituisce True se il lock è bloccato, altrimenti False.

acquire() → bool¶

Attende che il lock sia nello stato sbloccato e poi lo blocca in modo atomico. Solo un task alla volta può acquisire il lock.

Questa è una coroutine.

release() → None¶: Rilascia il lock. Se ci sono task in attesa del lock, il successivo nella coda viene pianificato per l’esecuzione e il lock rimane bloccato. Altrimenti, se nessun task è in attesa, il lock diventa sbloccato.

Connessioni stream TCP¶

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

Apre una connessione TCP verso l”host e la port specificati. L’indirizzo host verrà risolto usando socket.getaddrinfo(), che attualmente è una chiamata bloccante. Se ssl è un oggetto ssl.SSLContext, questo contesto viene usato per creare il trasporto; se ssl è True, viene usato un contesto predefinito.

Restituisce una coppia di stream: uno stream reader e uno stream writer. Solleverà un OSError specifico del socket se non è stato possibile risolvere l’host o se non è stato possibile stabilire la connessione.

Questa è una coroutine.

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

Avvia un server TCP sull”host e la port specificati. La callback verrà chiamata con le connessioni in ingresso accettate, e riceverà 2 argomenti: gli stream reader e writer della connessione.

Se ssl è un oggetto ssl.SSLContext, questo contesto viene usato per creare il trasporto.

Restituisce un oggetto Server.

Questa è una coroutine.

class asyncio.Stream¶

Questo rappresenta una connessione stream TCP. Per ridurre al minimo il codice, questa classe implementa sia un reader che un writer, e sia StreamReader che StreamWriter sono alias di questa classe.

get_extra_info(v: str) → Any¶: Ottiene informazioni aggiuntive sullo stream, indicate da v. I valori validi per v sono: peername.

close() → None¶: Chiude lo stream.

wait_closed() → None¶

Attende la chiusura dello stream.

Questa è una coroutine.

read(n: int = -1) → bytes¶

Legge fino a n byte e li restituisce. Se n non viene fornito oppure è -1, legge tutti i byte fino a EOF. Il valore restituito sarà un oggetto bytes vuoto se viene incontrato EOF prima della lettura di qualsiasi byte.

Questa è una coroutine.

readinto(buf: bytearray | memoryview) → int¶

Legge fino a n byte in buf, con n pari alla lunghezza di buf.

Restituisce il numero di byte letti in buf.

Questa è una coroutine, oltre che un’estensione di MicroPython.

readexactly(n: int) → bytes¶

Legge esattamente n byte e li restituisce come oggetto bytes.

Solleva un’eccezione EOFError se lo stream termina prima di leggere n byte.

Questa è una coroutine.

readline() → bytes¶

Legge una riga e la restituisce.

Questa è una coroutine.

write(buf: bytes) → None¶: Accumula buf nel buffer di output. I dati vengono scaricati solo quando viene chiamato Stream.drain(). Si consiglia di chiamare Stream.drain() immediatamente dopo aver chiamato questa funzione.

drain() → None¶

Scarica (scrive) tutti i dati di output bufferizzati verso lo stream.

Questa è una coroutine.

class asyncio.Server¶

Questo rappresenta la classe server restituita da start_server(). Può essere usata in un’istruzione async with per chiudere il server all’uscita.

close() → None¶: Chiude il server.

wait_closed() → None¶

Attende la chiusura del server.

Questa è una coroutine.

Event Loop¶

asyncio.get_event_loop() → Loop¶: Restituisce l’event loop usato per pianificare ed eseguire i task. Vedi Loop.

asyncio.new_event_loop() → Loop¶

Resetta l’event loop e lo restituisce.

Nota: poiché MicroPython ha un solo event loop, questa funzione si limita a resettare lo stato del loop, non ne crea uno nuovo.

class asyncio.Loop¶

Questo rappresenta l’oggetto che pianifica ed esegue i task. Non può essere creato; usa invece get_event_loop().

create_task(coro: Coroutine) → Task¶: Crea un task a partire dalla coro specificata e restituisce il nuovo oggetto Task.

run_forever() → None¶: Esegue l’event loop finché non viene chiamato stop().

run_until_complete(awaitable: Awaitable) → Any¶: Esegue l”awaitable specificato fino al suo completamento. Se awaitable non è un task, verrà promosso a task.

stop() → None¶: Arresta l’event loop.

close() → None¶: Chiude l’event loop.

set_exception_handler(handler: Callable) → None¶: Imposta il gestore delle eccezioni da chiamare quando un Task solleva un’eccezione non intercettata. Il handler deve accettare due argomenti: (loop, context).

get_exception_handler() → Callable | None¶: Ottiene il gestore delle eccezioni corrente. Restituisce il gestore, oppure None se non è impostato alcun gestore personalizzato.

default_exception_handler(context: dict) → None¶: Il gestore delle eccezioni predefinito che viene chiamato.

call_exception_handler(context: dict) → None¶: Chiama il gestore delle eccezioni corrente. L’argomento context viene passato direttamente ed è un dizionario contenente le chiavi: 'message', 'exception', 'future'.

asyncio — scheduler di I/O asincrono¶

Funzioni principali¶

Funzioni aggiuntive¶

class Task¶

class Event¶

class ThreadSafeFlag¶

class Lock¶

Connessioni stream TCP¶

Event Loop¶

`asyncio` — scheduler di I/O asincrono¶