# Desenvolvendo com asyncio

A programação assíncrona é diferente da programação “sequencial” clássica.

Esta página lista erros e armadilhas comuns e explica como evitá-los.

## Modo de Depuração

Por padrão, o asyncio é executado em modo de produção. Para facilitar o desenvolvimento, o asyncio fornece um modo de depuração.

Há várias maneiras de habilitar o modo de depuração do asyncio:

- Definindo a variável de ambiente `PYTHONASYNCIODEBUG` como `1`.

- Usando o Modo de Desenvolvimento do Python.

- Passando `debug=True` para `asyncio.run()`.

- Chamando `loop.set_debug()`.

Além de habilitar o modo de depuração, considere também:

- setting the log level of the asyncio logger to `logging.DEBUG`, for example the following snippet of code can be run at startup of the application:

      logging.basicConfig(level=logging.DEBUG)

- configurando o módulo `warnings` para exibir avisos `ResourceWarning`. Uma forma de fazer isso é usando a opção de linha de comando: `-W` `default`.

Quando o modo de depuração está habilitado:

- asyncio checks for coroutines that were not awaited and logs them; this mitigates the “forgotten await” pitfall.

- Muitas APIs do asyncio que não são thread-safe (como os métodos `loop.call_soon()` e `loop.call_at()`) levantam uma exceção se forem chamadas a partir de uma thread incorreta.

- O tempo de execução de um seletor de E/S é registrado se demorar muito para executar a operação E/S.

- Callbacks taking longer than 100ms are logged. The `loop.slow_callback_duration` attribute can be used to set the minimum execution duration in seconds that is considered “slow”.

## Concorrência e Múltiplas Threads

Um laço de eventos é executado em uma thread (geralmente a thread principal) e executa todos as funções de retorno e Tasks nessa mesma thread. Enquanto uma Task está em execução no laço de eventos, nenhuma outra Task pode ser executada na mesma thread. Quando uma Task executa uma expressão `await`, a Task em execução é suspensa, e o laço de eventos passa a executar a próxima Task.

Para agendar uma callback de outra thread do SO, o método `loop.call_soon_threadsafe()` deve ser usado. Exemplo:

    loop.call_soon_threadsafe(callback, *args)

Quase todos os objetos do asyncio não são seguros para threads, o que normalmente não é um problema, a menos que exista código que funcione com eles fora de uma Task ou de um callback. Se houver a necessidade de esse tipo de código chamar uma API de baixo nível do asyncio, o método `loop.call_soon_threadsafe()` deve ser usado, por exemplo:

    loop.call_soon_threadsafe(fut.cancel)

Para agendar um objeto corrotina a partir de uma thread diferente do sistema operacional, a função `run_coroutine_threadsafe()` deve ser usada. Ela retorna um `concurrent.futures.Future`. para acessar o resultado:

    async def coro_func():
         return await asyncio.sleep(1, 42)

    # Later in another OS thread:

    future = asyncio.run_coroutine_threadsafe(coro_func(), loop)
    # Wait for the result:
    result = future.result()

Para tratar sinais e executar subprocessos, o laço de eventos precisa executar na thread principal.

The `loop.run_in_executor()` method can be used with a `concurrent.futures.ThreadPoolExecutor` to execute blocking code in a different OS thread without blocking the OS thread that the event loop runs in.

There is currently no way to schedule coroutines or callbacks directly from a different process (such as one started with `multiprocessing`). The Métodos do laço de eventos section lists APIs that can read from pipes and watch file descriptors without blocking the event loop. In addition, asyncio’s Subprocess APIs provide a way to start a process and communicate with it from the event loop. Lastly, the aforementioned `loop.run_in_executor()` method can also be used with a `concurrent.futures.ProcessPoolExecutor` to execute code in a different process.

## Executando código bloqueante

O código bloqueante (vinculada à CPU) não deve ser chamado diretamente. Por exemplo, se uma função executa um cálculo pesado de CPU durante 1 segundo, todas as Tasks concorrentes do asyncio e as operações de E/S serão atrasadas por 1 segundo.

An executor can be used to run a task in a different thread or even in a different process to avoid blocking the OS thread with the event loop. See the `loop.run_in_executor()` method for more details.

## Gerando logs

asyncio usa o módulo `logging` e todo registro é feito via o registrador `"asyncio"`.

O nível de log padrão é `logging.INFO`, mas pode ser facilmente ajustado:

    logging.getLogger("asyncio").setLevel(logging.WARNING)

Logging de rede pode bloquear o laço de eventos. Recomenda-se usar uma thread separada para lidar com os logs ou usar E/S não bloqueante. Por exemplo, veja Dealing with handlers that block.

## Detectar corrotinas nunca aguardadas

Quando uma função de corrotina é chamada, mas não é aguardada (por exemplo, `coro()` em vez de `await coro()`) ou a corrotina não é agendada com `asyncio.create_task()`, o asyncio emitirá um `RuntimeWarning`:

    import asyncio

    async def test():
        print("never scheduled")

    async def main():
        test()

    asyncio.run(main())

Saída:

    test.py:7: RuntimeWarning: coroutine 'test' was never awaited
      test()

Saída no modo de depuração:

    test.py:7: RuntimeWarning: coroutine 'test' was never awaited
    Coroutine created at (most recent call last)
      File "../t.py", line 9, in <module>
        asyncio.run(main(), debug=True)

      < .. >

      File "../t.py", line 7, in main
        test()
      test()

A correção usual é aguardar a corrotina ou chamar a função `asyncio.create_task()`:

    async def main():
        await test()

## Detectar exceções nunca recuperadas

Se um `Future.set_exception()` é chamado, mas o objeto Future nunca é aguardado, a exceção nunca será propagada para o código do usuário. Nesse caso, o asyncio emitirá uma mensagem de log quando o objeto Future for coletado pela coleta de lixo.

Exemplo de uma exceção não tratada:

    import asyncio

    async def bug():
        raise Exception("not consumed")

    async def main():
        asyncio.create_task(bug())

    asyncio.run(main())

Saída:

    Task exception was never retrieved
    future: <Task finished coro=<bug() done, defined at test.py:3>
      exception=Exception('not consumed')>

    Traceback (most recent call last):
      File "test.py", line 4, in bug
        raise Exception("not consumed")
    Exception: not consumed

Enable the debug mode to get the traceback where the task was created:

    asyncio.run(main(), debug=True)

Saída no modo de depuração:

    Task exception was never retrieved
    future: <Task finished coro=<bug() done, defined at test.py:3>
        exception=Exception('not consumed') created at asyncio/tasks.py:321>

    source_traceback: Object created at (most recent call last):
      File "../t.py", line 9, in <module>
        asyncio.run(main(), debug=True)

    < .. >

    Traceback (most recent call last):
      File "../t.py", line 4, in bug
        raise Exception("not consumed")
    Exception: not consumed