`asyncio` — escalonador de I/O assíncrono¶

Este módulo fornece um escalonador de multitarefa cooperativa para corrotinas async/await, juntamente com primitivos de sincronização (bloqueios, eventos) e rede TCP não bloqueante via leitores e escritores de fluxo. As tarefas são executadas de forma concorrente num único ciclo de eventos; a tarefa em execução cede o controlo ao ciclo com await.

Exemplo:

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

Funções principais¶

asyncio.create_task(coro: Coroutine) → Task¶

Cria uma nova tarefa a partir da corrotina indicada e agenda a sua execução.

Devolve o objeto Task correspondente.

asyncio.current_task() → Task¶: Devolve o objeto Task associado à tarefa em execução no momento.

asyncio.run(coro: Coroutine) → Any¶

Cria uma nova tarefa a partir da corrotina indicada e executa-a até à conclusão.

Devolve o valor devolvido por coro.

asyncio.sleep(t: float) → None¶

Aguarda t segundos (pode ser um número de vírgula flutuante).

Esta é uma corrotina.

asyncio.sleep_ms(t: int) → None¶

Aguarda t milissegundos.

Esta é uma corrotina e uma extensão MicroPython.

Funções adicionais¶

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

Aguarda a conclusão do awaitable, mas cancela-o se demorar mais de timeout segundos. Se awaitable não for uma tarefa, será criada uma tarefa a partir dele.

Se ocorrer um tempo limite, a tarefa é cancelada e é lançada a exceção asyncio.TimeoutError: esta deve ser tratada pelo chamador. A tarefa recebe asyncio.CancelledError, que pode ser ignorada ou tratada com try...except ou try...finally para executar código de limpeza.

Devolve o valor de retorno de awaitable.

Esta é uma corrotina.

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

Semelhante a wait_for(), mas timeout é um inteiro em milissegundos.

Esta é uma corrotina e uma extensão MicroPython.

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

Executa todos os awaitables de forma concorrente. Os awaitables que não sejam tarefas são promovidos a tarefas.

Devolve uma lista com os valores de retorno de todos os awaitables.

Esta é uma corrotina.

class Task¶

class asyncio.Task¶

Este objeto encapsula uma corrotina numa tarefa em execução. As tarefas podem ser aguardadas com await task, o que aguardará a conclusão da tarefa e devolverá o seu valor de retorno.

As tarefas não devem ser criadas diretamente; utilize create_task() para as criar.

cancel() → None¶: Cancela a tarefa injetando asyncio.CancelledError nela. A tarefa pode ignorar esta exceção. O código de limpeza pode ser executado capturando a exceção ou com try ... finally.

class Event¶

class asyncio.Event¶

Cria um novo evento que pode ser utilizado para sincronizar tarefas. Os eventos são iniciados no estado limpo.

is_set() → bool¶: Devolve True se o evento estiver definido, False caso contrário.

set() → None¶

Define o evento. Quaisquer tarefas à espera do evento serão agendadas para execução.

Nota: Este método deve ser chamado a partir de uma tarefa. Não é seguro chamá-lo a partir de uma IRQ, callback do escalonador ou outra thread. Consulte ThreadSafeFlag.

clear() → None¶: Limpa o evento.

wait() → None¶

Aguarda que o evento seja definido. Se o evento já estiver definido, retorna imediatamente.

Esta é uma corrotina.

class ThreadSafeFlag¶

class asyncio.ThreadSafeFlag¶

Cria uma nova bandeira que pode ser utilizada para sincronizar uma tarefa com código a executar fora do ciclo asyncio, como outras threads, IRQs ou callbacks do escalonador. As bandeiras são iniciadas no estado limpo.

set() → None¶: Define a bandeira. Se houver uma tarefa à espera da bandeira, esta será agendada para execução.

clear() → None¶: Limpa a bandeira. Pode ser utilizado para garantir que uma bandeira possivelmente definida anteriormente seja limpa antes de aguardar por ela.

wait() → None¶

Aguarda que a bandeira seja definida. Se a bandeira já estiver definida, retorna imediatamente. A bandeira é automaticamente reposta após o retorno de wait.

Uma bandeira só pode ser aguardada por uma única tarefa de cada vez.

Esta é uma corrotina.

class Lock¶

class asyncio.Lock¶

Cria um novo bloqueio que pode ser utilizado para coordenar tarefas. Os bloqueios são iniciados no estado desbloqueado.

Para além dos métodos abaixo, os bloqueios podem ser utilizados numa instrução async with.

locked() → bool¶: Devolve True se o bloqueio estiver bloqueado, False caso contrário.

acquire() → bool¶

Aguarda que o bloqueio esteja no estado desbloqueado e, em seguida, bloqueia-o de forma atómica. Apenas uma tarefa pode adquirir o bloqueio de cada vez.

Esta é uma corrotina.

release() → None¶: Liberta o bloqueio. Se houver tarefas à espera do bloqueio, a próxima na fila é agendada para execução e o bloqueio permanece bloqueado. Caso contrário, não há tarefas à espera e o bloqueio passa ao estado desbloqueado.

Ligações TCP de fluxo¶

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

Abre uma ligação TCP ao host e port indicados. O endereço de host será resolvido com socket.getaddrinfo(), que é atualmente uma chamada bloqueante. Se ssl for um objeto ssl.SSLContext, este contexto é utilizado para criar o transporte; se ssl for True, é utilizado um contexto predefinido.

Devolve um par de fluxos: um leitor e um escritor. Lançará um OSError específico de socket se o host não puder ser resolvido ou se a ligação não puder ser estabelecida.

Esta é uma corrotina.

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

Inicia um servidor TCP no host e port indicados. O callback será chamado com as ligações recebidas e aceites, recebendo 2 argumentos: fluxos de leitura e escrita para a ligação.

Se ssl for um objeto ssl.SSLContext, este contexto é utilizado para criar o transporte.

Devolve um objeto Server.

Esta é uma corrotina.

class asyncio.Stream¶

Representa uma ligação TCP de fluxo. Para minimizar o código, esta classe implementa tanto um leitor como um escritor, e tanto StreamReader como StreamWriter são alias desta classe.

get_extra_info(v: str) → Any¶: Obtém informações adicionais sobre o fluxo, indicadas por v. Os valores válidos para v são: peername.

close() → None¶: Fecha o fluxo.

wait_closed() → None¶

Aguarda que o fluxo seja fechado.

Esta é uma corrotina.

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

Lê até n bytes e devolve-os. Se n não for fornecido ou for -1, lê todos os bytes até ao EOF. O valor devolvido será um objeto bytes vazio se o EOF for encontrado antes de qualquer byte ser lido.

Esta é uma corrotina.

readinto(buf: bytearray | memoryview) → int¶

Lê até n bytes para buf, sendo n igual ao comprimento de buf.

Devolve o número de bytes lidos para buf.

Esta é uma corrotina e uma extensão MicroPython.

readexactly(n: int) → bytes¶

Lê exatamente n bytes e devolve-os como objeto bytes.

Lança uma exceção EOFError se o fluxo terminar antes de ler n bytes.

Esta é uma corrotina.

readline() → bytes¶

Lê uma linha e devolve-a.

Esta é uma corrotina.

write(buf: bytes) → None¶: Acumula buf no buffer de saída. Os dados só são enviados quando Stream.drain() é chamado. Recomenda-se chamar Stream.drain() imediatamente após chamar esta função.

drain() → None¶

Esvazia (escreve) todos os dados de saída em buffer para o fluxo.

Esta é uma corrotina.

class asyncio.Server¶

Representa a classe de servidor devolvida por start_server(). Pode ser utilizada numa instrução async with para fechar o servidor ao sair.

close() → None¶: Fecha o servidor.

wait_closed() → None¶

Aguarda que o servidor seja fechado.

Esta é uma corrotina.

Ciclo de Eventos¶

asyncio.get_event_loop() → Loop¶: Devolve o ciclo de eventos utilizado para agendar e executar tarefas. Consulte Loop.

asyncio.new_event_loop() → Loop¶

Reinicia o ciclo de eventos e devolve-o.

Nota: como o MicroPython tem apenas um único ciclo de eventos, esta função limita-se a repor o estado do ciclo, não cria um novo.

class asyncio.Loop¶

Representa o objeto que agenda e executa tarefas. Não pode ser criado diretamente; utilize get_event_loop() em vez disso.

create_task(coro: Coroutine) → Task¶: Cria uma tarefa a partir de coro e devolve o novo objeto Task.

run_forever() → None¶: Executa o ciclo de eventos até que stop() seja chamado.

run_until_complete(awaitable: Awaitable) → Any¶: Executa o awaitable indicado até à sua conclusão. Se awaitable não for uma tarefa, será promovido a uma.

stop() → None¶: Para o ciclo de eventos.

close() → None¶: Fecha o ciclo de eventos.

set_exception_handler(handler: Callable) → None¶: Define o tratador de exceções a chamar quando uma Task lança uma exceção não capturada. O handler deve aceitar dois argumentos: (loop, context).

get_exception_handler() → Callable | None¶: Obtém o tratador de exceções atual. Devolve o tratador, ou None se nenhum tratador personalizado estiver definido.

default_exception_handler(context: dict) → None¶: O tratador de exceções predefinido que é chamado.

call_exception_handler(context: dict) → None¶: Chama o tratador de exceções atual. O argumento context é passado diretamente e é um dicionário contendo as chaves: 'message', 'exception', 'future'.

asyncio — escalonador de I/O assíncrono¶

Funções principais¶

Funções adicionais¶

class Task¶

class Event¶

class ThreadSafeFlag¶

class Lock¶

Ligações TCP de fluxo¶

Ciclo de Eventos¶

`asyncio` — escalonador de I/O assíncrono¶