Skip to content

9. Programação assíncrona com corrotinas

O capítulo anterior apresentou as threads: é possível executar vários trechos de código “ao mesmo tempo”, sincronizá-los e atribuir tarefas a um pool de threads por meio de um executor ([ExecutorService]). Este capítulo trata de um problema relacionado, mas distinto: como escrever um programa que espera muito (pelo disco, pela rede ou por um banco de dados) sem prender threads durante essas esperas.

Este é o capítulo em que o Kotlin mais se afasta do Java. O curso de Java apresentou duas soluções: a classe [CompletableFuture<T>], cujo comportamento é estendido por meio de métodos de callback, e as threads virtuais do Java 21, que permitem escrever código bloqueante sem bloquear nenhuma thread do sistema. Ambas as ferramentas continuam disponíveis em Kotlin (são classes do JDK) e voltaremos a elas. Mas o Kotlin oferece uma solução própria: as corrotinas:

  • a linguagem inclui apenas uma única palavra-chave, [suspend], que marca uma função de suspensão: uma função que pode fazer uma pausa no meio de sua execução, liberar a thread que a executa e retomar mais tarde no mesmo ponto, com os mesmos valores de variáveis locais;
  • o compilador transforma cada função de suspensão em uma “máquina de estados” capaz de pausar e retomar; veremos como;
  • Todo o resto é fornecido por uma biblioteca, kotlinx.coroutines: iniciar corrotinas ([launch], [async]), esperar por elas ([join], [await]), esperar sem bloquear ([delay]), escolher as threads que as executam (os dispatchers), cancelá-las, limitar sua duração e passar valores entre elas ([Flow], [Channel]).

O código resultante é lido de cima para baixo como um código sequencial: é equivalente às palavras-chave do C# [async] / [await], com as quais os leitores do curso original estão familiarizados, mais um conceito que nem o C# nem o Java (exceto de forma preliminar) oferecem: a concorrência estruturada, que organiza as corrotinas em uma árvore em que cada nó espera por seus filhos, os cancela e recebe seus erros.

As corrotinas são hoje onipresentes no ecossistema Kotlin: no Android, em frameworks web (Ktor, Spring, que aceita funções [suspend] em seus controllers), em clientes HTTP e em drivers de banco de dados. Os próximos capítulos as usarão para acessar bancos de dados e a rede.

A biblioteca kotlinx.coroutines não faz parte da biblioteca padrão: o projeto Gradle deste capítulo, localizado na pasta [09-async], a declara em seu arquivo [build.gradle.kts]:

// capítulo 9: programação assíncrona com corrotinas
plugins {
    kotlin("jvm") version "2.4.20"
    application
}

group = "examples"
version = "1.0"

repositories {
    mavenCentral()
}

dependencies {
    // as bibliotecas usadas pelos programas do projeto
    // corrotinas Kotlin
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")
}

kotlin {
    // o código é compilado e executado com o JDK 25
    jvmToolchain(25)
    compilerOptions {
        // um aviso do compilador é tratado como erro
        allWarningsAsErrors = true
        // os nomes dos parâmetros das funções são mantidos no bytecode
        javaParameters = true
    }
}

application {
    // o programa executado por [gradlew run] é dado pela propriedade [main]:
    // gradlew -q run -Pmain=async01.Async01Kt
    mainClass = providers.gradleProperty("main").orElse("async01.Async01Kt")
}

tasks.named<JavaExec>("run") {
    // o programa em execução pode ler o teclado
    standardInput = System.`in`
}

// no Windows, a saída de tela do programa iniciado pelo Gradle (run, bootRun...) é codificada em UTF-8,
// caso contrário os caracteres acentuados ficam corrompidos no console do IntelliJ IDEA ou no terminal
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}
  • linha 17: a dependência da biblioteca kotlinx.coroutines, versão 1.11.0. O pacote principal é [kotlinx.coroutines];
  • linhas 32–34: como nos capítulos anteriores, o programa a ser executado é identificado pela propriedade [main]: [gradlew -q run -Pmain=async01.Async01Kt];
  • linhas 42–45: os programas iniciados pelo Gradle escrevem sua saída em UTF-8 para que os caracteres acentuados sejam exibidos corretamente no Windows (Capítulo 2).

Os programas deste capítulo são organizados, como de costume, em pacotes com o nome deles: [src/main/kotlin/async01/Async01.kt], [src/main/kotlin/async02/Async02.kt]… Muitos deles medem durações usando [System.nanoTime()]: os milissegundos exibidos variam de uma execução para outra e de uma máquina para outra (os exemplos foram executados em uma máquina com dois processadores). O que importa são as ordens de grandeza: 1 segundo ou 10 segundos, 300 ms ou 0 ms. O primeiro uso de corrotinas em um programa carrega as classes da biblioteca, o que muitas vezes acrescenta algumas dezenas de milissegundos às primeiras medições.

9.1. Por que a assincronia

9.1.1. Operações que esperam

Um programa realiza dois tipos de trabalho:

  • tarefas de cálculo, que ocupam o processador: ordenar uma lista, calcular um imposto, analisar um texto;
  • entrada/saída (E/S), que consiste essencialmente em esperar por um dispositivo: ler um arquivo do disco, enviar uma requisição a um servidor web e esperar pela resposta, executar uma consulta SQL em um servidor de banco de dados.

As ordens de grandeza são muito diferentes. Um processador executa alguns bilhões de instruções por segundo. Uma operação de leitura em um disco (SSD) leva da ordem de um décimo de milissegundo; uma viagem de ida e volta em uma rede local leva uma fração de milissegundo; uma viagem de ida e volta a um servidor situado do outro lado do país leva algumas dezenas de milissegundos; e uma requisição SQL um pouco complexa pode às vezes levar vários segundos. Durante essas esperas, o processador poderia ter executado milhões de instruções.

Quando um programa lê uma linha em uma conexão de rede usando uma função bloqueante, a thread que executa essa leitura fica bloqueada: ela não faz nada, mas continua existindo. Uma thread “clássica” da JVM, agora chamada de “thread de plataforma”, é uma thread do sistema operacional: ela ocupa memória (sua pilha, da ordem de um megabyte), é reconhecida pelo sistema e, principalmente, deixa de estar disponível para fazer qualquer outra coisa. Isso não é um problema em um pequeno programa de console que faz uma coisa de cada vez. Mas é bem mais problemático em duas situações:

  • em um servidor: cada cliente atendido por uma thread bloqueada prende essa thread. Se o pool de threads do servidor tem N threads e todas as N estão executando uma operação bloqueante, não resta nenhuma thread disponível para um novo cliente. Um servidor moderno atende milhares de requisições simultâneas: isso é possível porque suas operações de espera não prendem threads do sistema;
  • em uma interface gráfica de usuário: uma única thread, a thread da interface (a thread principal de um aplicativo Android, a “Event Dispatch Thread” do Swing, a “JavaFX Application Thread”), trata os cliques e redesenha as janelas. Se ela for bloqueada por um download, a janela congela; no Android, o sistema chega até a propor ao usuário que feche o aplicativo.

A assincronia consiste em iniciar a operação de E/S, liberar a thread do sistema enquanto ela é executada (o hardware e o sistema operacional não precisam dela para transferir os dados) e depois retomar o trabalho quando a operação terminar, possivelmente em outra thread. As threads virtuais do Java fazem isso no nível da JVM: uma thread virtual bloqueada é desvinculada de sua thread hospedeira, que, nesse meio-tempo, continua executando outras threads virtuais. As corrotinas do Kotlin fazem isso no nível do código compilado: uma corrotina em espera é suspensa, ou seja, seu estado (o ponto em que parou e suas variáveis locais) é armazenado em um objeto do heap chamado continuação, e a thread que a executava é devolvida ao seu pool:

Image

  • Em [1], a thread do sistema T1 executa uma função bloqueante; ela permanece bloqueada até que a E/S termine;
  • Em [2], a corrotina C1 chama uma função de suspensão que inicia a E/S; a corrotina é suspensa: sua continuação é armazenada no heap, e a thread T1 que a executava pode executar imediatamente outras corrotinas. Quando a E/S termina, a continuação é retomada por uma thread livre, T2 (que também poderia ser T1), e C1 prossegue sua execução logo após a chamada da função de suspensão, como se nada tivesse acontecido.

O programa [Async01.kt] mede a diferença em 100 operações, cada uma das quais espera um segundo (a espera simula uma E/S). Ele usa instruções que explicaremos mais adiante neste capítulo ([runBlocking], [launch], [delay]): aqui, o que nos interessa primeiro são os resultados.

// por que assincronia: 100 operações que esperam cada uma um segundo
// (uma espera simula uma E/S: leitura de disco, requisição de rede, consulta SQL…)
package async01

import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import java.lang.management.ManagementFactory
import java.util.concurrent.Executors
import kotlin.concurrent.thread

const val NB_OPERATIONS = 100
var start = 0L

fun main() {
    val nbProcessors = Runtime.getRuntime().availableProcessors()
    println("$NB_OPERATIONS one-second operations, $nbProcessors processors")

    // 1 - uma thread de plataforma por operação, cada thread fica bloqueada durante a espera
    start = System.nanoTime()
    val threads = List(NB_OPERATIONS) { thread { Thread.sleep(1000) } }
    waitUntilHalfway()
    display("1 - one platform thread per operation", jvmThreads())
    threads.forEach { it.join() }
    display("    end")

    // 2 - as operações são entregues a um pool de 10 threads, mas elas o bloqueiam
    start = System.nanoTime()
    Executors.newFixedThreadPool(10).use { pool ->
        repeat(NB_OPERATIONS) { pool.execute { Thread.sleep(1000) } }
        waitUntilHalfway()
        display("2 - pool of 10 threads, blocking waits", jvmThreads())
    } // close() espera o fim de todas as operações
    display("    end")

    // 3 - uma thread virtual por operação: ela libera sua carrier thread durante a espera
    start = System.nanoTime()
    Executors.newVirtualThreadPerTaskExecutor().use { executor ->
        repeat(NB_OPERATIONS) { executor.execute { Thread.sleep(1000) } }
        waitUntilHalfway()
        display("3 - one virtual thread per operation", jvmThreads())
    }
    display("    end")

    // 4 - uma corrotina por operação: delay suspende a corrotina sem bloquear uma thread
    start = System.nanoTime()
    runBlocking {
        repeat(NB_OPERATIONS) { launch { delay(1000) } }
        // uma espera que também suspende: a thread continua disponível para as corrotinas
        delay(500 - elapsed())
        display("4 - one coroutine per operation", jvmThreads())
    } // runBlocking espera o fim de todas as corrotinas que ele lançou
    display("    end")

    // 5 - cem mil corrotinas, ainda na única thread [main]
    start = System.nanoTime()
    runBlocking {
        repeat(100_000) { launch { delay(1000) } }
        delay(500 - elapsed())
        display("5 - 100,000 coroutines", jvmThreads())
    }
    display("    end")
}

// milissegundos decorridos desde [start]
fun elapsed(): Long = (System.nanoTime() - start) / 1_000_000

// espera bloqueante até 500 ms após [start]
fun waitUntilHalfway() {
    val remaining = 500 - elapsed()
    if (remaining > 0) Thread.sleep(remaining)
}

// número de threads de plataforma vivas da JVM
fun jvmThreads(): Int = ManagementFactory.getThreadMXBean().threadCount

// exibição do tempo decorrido e, se fornecido (>= 0), do número de threads
fun display(message: String, nbThreads: Int = -1) {
    val threadsInfo = if (nbThreads < 0) "" else ", %3d threads in the JVM".format(nbThreads)
    println("%-44s : %5d ms%s".format(message, elapsed(), threadsInfo))
}

Resultados:

> gradlew -q run -Pmain=async01.Async01Kt
100 one-second operations, 2 processors
1 - one platform thread per operation        :   530 ms, 106 threads in the JVM
    end                                      :  1035 ms
2 - pool of 10 threads, blocking waits       :   500 ms,  16 threads in the JVM
    end                                      : 10009 ms
3 - one virtual thread per operation         :   501 ms,  10 threads in the JVM
    end                                      :  1014 ms
4 - one coroutine per operation              :   504 ms,  10 threads in the JVM
    end                                      :  1059 ms
5 - 100,000 coroutines                       :   501 ms,  10 threads in the JVM
    end                                      :  1341 ms

Comentários:

  • Linhas 19–25: a solução mais simples, uma thread de plataforma por operação. A função [thread { … }] de [kotlin.concurrent] (Capítulo 8) cria e inicia uma thread; [List(NB_OPERATIONS) { … }] constrói a lista de 100 threads. Cada thread executa [Thread.sleep(1000)]: ela fica bloqueada por um segundo. As 100 esperas ocorrem simultaneamente, e o processo inteiro leva exatamente um segundo (linha 4 dos resultados), mas ao custo de 100 threads de sistema adicionais: a JVM contabiliza 106 (linha 3). Com 10.000 operações, seriam necessárias 10.000 threads de sistema;
  • Linhas 27–34: as operações são atribuídas a um pool de 10 threads ([Executors.newFixedThreadPool(10)]), um tamanho razoável para cálculos. Mas aqui essas threads não fazem cálculos: ficam ociosas. As operações esperam uma thread livre, em lotes de 10, e o processo inteiro leva… dez segundos (linha 6). É o que se chama de “inanição do pool de threads”, o defeito mais comum em servidores que misturam pools de threads com E/S bloqueante. Um [ExecutorService] é [AutoCloseable] (Java 19): a função [use] chama seu método [close()] ao fim do bloco, que rejeita novas tarefas e espera as que já foram submetidas terminarem ([use] desempenha o mesmo papel que [try] com um recurso em Java);
  • linhas 36–43: uma thread virtual por operação. O código da tarefa é o mesmo do passo 1: um [Thread.sleep(1000)]bloqueante. No entanto, uma thread virtual bloqueada não bloqueia nenhuma thread do sistema. As 100 esperas juntas duram um segundo (linha 8), e a JVM tem apenas 10 threads de sistema (linha 7): suas threads de serviço e as duas threads portadoras, uma por processador. Esta é a solução do curso de Java;
  • linhas 45–53: uma corrotina por operação. [runBlocking { … }] executa um bloco de código como uma corrotina na thread que o chama (aqui, a thread [main]), e só devolve o controle ao final dessa corrotina e de todas as que ela iniciou. Dentro do bloco, [launch { delay(1000) }] inicia uma nova corrotina que espera um segundo: [delay] é uma função de suspensão que suspende a corrotina sem bloquear a thread. As 100 corrotinas são executadas pela única thread [main]: enquanto elas esperam, ela não lhes deve nada e executa as outras. A JVM continua com 10 threads (linha 9): nenhuma a mais que no passo anterior. O processo inteiro leva pouco mais de um segundo (linha 10), e o tempo extra vem do carregamento das classes da biblioteca, que ocorre nesse primeiro uso;
  • linha 50: para medir o número de threads na metade do caminho, a corrotina principal também espera com [delay]. Com [Thread.sleep], ela bloquearia a thread [main], que é a única que executa as 100 corrotinas: elas só poderiam começar quando essa espera terminasse. Voltaremos a essa diferença fundamental entre [delay] e [Thread.sleep];
  • linhas 55–62: cem mil corrotinas, ainda executadas somente pela thread [main], sem nenhuma thread adicional (linha 11). Uma corrotina suspensa é simplesmente um pequeno conjunto de objetos no heap, cada um com algumas dezenas de bytes: pode haver centenas de milhares delas. Criar as 100.000 corrotinas e seus temporizadores já leva algum tempo (algumas centenas de milissegundos na máquina do exemplo, daí o tempo mostrado na linha 12); já criar 100.000 threads de plataforma seria simplesmente impossível na maioria das máquinas;
  • linha 75: [ManagementFactory.getThreadMXBean().threadCount] retorna o número de threads de plataforma ativas da JVM. Em Kotlin, o método Java [getThreadCount()] é tratado como uma propriedade, [threadCount];
  • A função [thread] e seus executores usam [Thread.sleep] diretamente: o Kotlin não tem exceções verificadas (Capítulo 3), de modo que não é preciso capturar a [InterruptedException] que [Thread.sleep] pode lançar, como fazia o método [waitFor] no programa Java.

Guardemos a lição: para esperar, não se deve bloquear nenhuma thread do sistema. A assincronia não torna a E/S mais rápida; ela permite tratar muitas operações de E/S simultaneamente com poucas threads e manter disponíveis as threads de que a aplicação precisa. O Kotlin oferece duas abordagens: escrever código bloqueante comum executado por threads virtuais (passo 3, como em Java) ou escrever funções de suspensão executadas por corrotinas (passos 4 e 5). Este capítulo se concentra na segunda abordagem.

9.1.2. Vários modelos sucessivos

As plataformas ofereceram várias maneiras de escrever código que espera sem bloquear. As mais antigas ainda são encontradas em códigos existentes, e o Kotlin, que usa diretamente as bibliotecas Java, convive com elas: é útil reconhecê-las.

Modelo
Surgimento
Princípio
Threads e executores
Java 1.0 (1996), Java 5 (2004)
uma thread por operação ou um pool de threads ([ExecutorService]). [submit] retorna um [Future<T>], que representa o resultado futuro, mas a única maneira de obter esse resultado é esperar, de forma bloqueante, com [get()].
métodos de callback
Java 7 (NIO.2, 2011), JavaScript
uma operação é iniciada passando-lhe um objeto ou uma função de callback ([CompletionHandler] do NIO.2), que é chamada ao final da operação por uma thread de um pool.
futures componíveis
Java 8 ([CompletableFuture], 2014), promises do JavaScript
um objeto que representa a operação em andamento e cujas etapas seguintes são compostas por meio de métodos ([thenApply], [thenCompose], [exceptionally]…); as bibliotecas reativas (Project Reactor, RxJava) baseiam-se nas mesmas ideias.
[async] / [await]
C# 5 (2012), seguido por JavaScript, Python, Rust…
métodos [async] que retornam uma tarefa ([Task<T>] em C#); [await] suspende o método até que a tarefa termine, sem bloquear a thread. O compilador transforma o método em uma máquina de estados.
Corrotinas do Kotlin
Kotlin 1.3 (2018)
Funções [suspend] são transformadas pelo compilador em máquinas de estados, e a biblioteca kotlinx.coroutines fornece a concorrência estruturada. As chamadas a funções de suspensão não incluem nenhuma palavra-chave: o código tem a forma de um código sequencial.
Threads virtuais
Java 21 (2023)
Código bloqueante comum, executado por threads virtuais: a JVM libera a thread do sistema durante as esperas.

Os métodos de callback têm um inconveniente: o código fica fragmentado. O que naturalmente se lê como “conectar, depois ler, depois exibir” se torna uma função que inicia a conexão, uma função de callback que inicia a leitura e outra função de callback que exibe os dados; as variáveis precisam ser compartilhadas entre essas funções, as exceções são capturadas em lugares diferentes, e um simples laço (“ler enquanto houver dados”) se torna uma função de callback que chama a si mesma recursivamente. Os futures componíveis tornam essa fragmentação mais legível ao encadear as etapas; as corrotinas a eliminam por completo: o código assíncrono tem a forma de um código síncrono. A diferença em relação às threads virtuais é que é o compilador, e não a JVM, que divide o código nos pontos de espera.

O programa [Async02.kt] implementa o mesmo cliente TCP usando os dois modelos extremos: primeiro com os métodos de callback do NIO.2 e depois com uma corrotina. Ele também contém um pequeno servidor, executado por uma thread, que responde a dois clientes (a programação de rede será tratada em detalhes no Capítulo 12; por ora, basta saber que um cliente se conecta ao servidor e lê a mensagem que o servidor lhe envia).

// o mesmo cliente TCP escrito com métodos de callback (NIO.2) e depois com uma corrotina
package async02

import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.suspendCancellableCoroutine
import java.io.IOException
import java.net.InetAddress
import java.net.InetSocketAddress
import java.net.ServerSocket
import java.net.SocketAddress
import java.nio.ByteBuffer
import java.nio.channels.AsynchronousSocketChannel
import java.nio.channels.CompletionHandler
import java.util.concurrent.CountDownLatch
import kotlin.concurrent.thread
import kotlin.coroutines.resume
import kotlin.coroutines.resumeWithException

const val PORT = 27500
val local: InetAddress = InetAddress.getLoopbackAddress()

fun main() {
    // um servidor mínimo, executado por uma thread: ele atende dois clientes e depois para
    val listener = ServerSocket(PORT, 10, local)
    val server = thread(name = "server") {
        listener.use {
            for (i in 1..2) {
                listener.accept().use { service ->
                    // o servidor demora a responder
                    Thread.sleep(500)
                    service.getOutputStream().write("Hello client no. $i".toByteArray())
                }
            }
        }
    }
    display("start of the program")

    // 1 - o estilo "métodos de callback": AsynchronousSocketChannel e CompletionHandler
    val end = CountDownLatch(1)
    val client = AsynchronousSocketChannel.open()
    val buffer = ByteBuffer.allocate(1024)
    // a conexão é iniciada, informando o objeto a ser chamado de volta quando ela terminar
    client.connect(InetSocketAddress(local, PORT), Unit, object : CompletionHandler<Void?, Unit> {
        // método de callback nº 1: a conexão foi feita
        override fun completed(nothing: Void?, attachment: Unit) {
            display("callbacks: connected, read started")
            // a leitura da resposta é iniciada com um segundo objeto de callback
            client.read(buffer, Unit, object : CompletionHandler<Int, Unit> {
                // método de callback nº 2: dados chegaram
                override fun completed(nbBytes: Int, attachment: Unit) {
                    display("callbacks: received [${String(buffer.array(), 0, nbBytes)}]")
                    client.close()
                    // a thread principal é notificada
                    end.countDown()
                }

                override fun failed(e: Throwable, attachment: Unit) {
                    display("callbacks: read failed: $e")
                    end.countDown()
                }
            })
        }

        override fun failed(e: Throwable, attachment: Unit) {
            display("callbacks: connection failed: $e")
            end.countDown()
        }
    })
    display("callbacks: connection started, the program continues")
    // a thread principal não tem mais nada a fazer: ela espera o sinal do último método de callback
    end.await()

    // 2 - o mesmo cliente escrito com uma corrotina: o código é lido de cima para baixo
    runBlocking {
        try {
            AsynchronousSocketChannel.open().use { channel ->
                // duas funções suspensas: a corrotina é suspensa, nenhuma thread espera
                channel.connectTo(InetSocketAddress(local, PORT))
                display("coroutine: connected, read started")
                val buffer2 = ByteBuffer.allocate(1024)
                val nbBytes = channel.readInto(buffer2)
                display("coroutine: received [${String(buffer2.array(), 0, nbBytes)}]")
            }
        } catch (e: IOException) {
            display("coroutine: $e")
        }
    }
    server.join()
}

// a conexão com callback, transformada em uma função suspensa
suspend fun AsynchronousSocketChannel.connectTo(address: SocketAddress): Unit =
    suspendCancellableCoroutine { continuation ->
        connect(address, Unit, object : CompletionHandler<Void?, Unit> {
            // o método de callback retoma a corrotina suspensa…
            override fun completed(nothing: Void?, attachment: Unit) = continuation.resume(Unit)

            // … ou a retoma fazendo-a lançar a exceção
            override fun failed(e: Throwable, attachment: Unit) = continuation.resumeWithException(e)
        })
    }

// a leitura com callback, transformada em uma função suspensa que devolve o número de bytes lidos
suspend fun AsynchronousSocketChannel.readInto(buffer: ByteBuffer): Int =
    suspendCancellableCoroutine { continuation ->
        read(buffer, Unit, object : CompletionHandler<Int, Unit> {
            override fun completed(nbBytes: Int, attachment: Unit) = continuation.resume(nbBytes)
            override fun failed(e: Throwable, attachment: Unit) = continuation.resumeWithException(e)
        })
    }

// exibição prefixada pelo nome da thread que a executa
fun display(message: String) = println("[${Thread.currentThread().name}] $message")

Resultados:

1
2
3
4
5
6
7
> gradlew -q run -Pmain=async02.Async02Kt
[main] start of the program
[main] callbacks: connection started, the program continues
[InnocuousThread-4] callbacks: connected, read started
[InnocuousThread-2] callbacks: received [Hello client no. 1]
[main] coroutine: connected, read started
[main] coroutine: received [Hello client no. 2]

Comentários:

  • Linhas 23–36: o servidor. Ele escuta na porta 27500 da máquina local ([InetAddress.getLoopbackAddress()], isto é, 127.0.0.1), aceita duas conexões uma após a outra e envia a cada cliente uma mensagem de boas-vindas após meio segundo. Ele é executado por uma thread de plataforma chamada [server], criada pela função [thread] com o argumento nomeado [name]. As funções [use] fecham o [ServerSocket] e cada [Socket] de serviço ao final de seu bloco;
  • linhas 38–71: o cliente escrito com métodos de callback:
    • Linha 40: um [AsynchronousSocketChannel] é um canal TCP cujas operações são assíncronas;
    • Linha 43: [connect] inicia a conexão e devolve imediatamente o controle (linha 3 dos resultados). Seus dois últimos parâmetros são um objeto arbitrário que o método de callback receberá (aqui, [Unit], pois não precisamos dele) e o objeto de callback, que implementa a interface [CompletionHandler<V, A>], em que [V] é o tipo do resultado da operação ([Void?] para uma conexão, que não retorna nada) e [A] é o tipo do objeto passado. O Kotlin permite criar esse objeto na hora com uma expressão de objeto ([object : CompletionHandler<Void?, Unit> { … }]), equivalente às classes anônimas do Java. Seu método [completed] é chamado se a operação for bem-sucedida, e seu método [failed] se ela falhar;
    • linhas 44–48: depois de conectado, a leitura é iniciada com *[read]*, especificando um segundo objeto de callback aninhado no primeiro;
    • linhas 49–54: o objeto de callback de leitura recebe o número de bytes lidos, exibe a mensagem, fecha o canal e libera a thread principal;
    • linha 71: a thread principal não tem mais nada a fazer. Para garantir que o programa não termine antes do fim da troca, ela espera um sinal do último método de callback: um *[CountDownLatch] inicializado com 1, cujo método *[await]* bloqueia a thread chamadora até que outra thread chame seu método *[countDown] ;
  • os resultados mostram que os métodos de callback são executados por threads diferentes da thread principal (threads do pool da JVM dedicado aos canais assíncronos, chamadas [InnocuousThread-N]). O aninhamento dos dois objetos de callback já dificulta o acompanhamento do código; com três ou quatro operações sucessivas, chega-se ao que se chama de “callback hell”;
  • linhas 73–88: o mesmo cliente escrito com uma corrotina iniciada por [runBlocking]. O código é lido de cima para baixo, exatamente como um código síncrono: conectar, ler, exibir. As variáveis são variáveis locais comuns; os erros são tratados por um único [try / catch]; não há objetos de callback aninhados nem sinais a gerenciar. No entanto, nenhuma thread espera pela conexão ou pela resposta do servidor: [connectTo] e [readInto] são funções de suspensão, que suspendem a corrotina durante a operação;
  • linhas 92–99: a função [connectTo] converte a operação com callback em uma função de suspensão. Ela é uma função de extensão (Capítulo 4) de [AsynchronousSocketChannel], marcada com [suspend]. A função [suspendCancellableCoroutine] da kotlinx.coroutines suspende a corrotina que a chama e passa ao bloco a continuação dessa corrotina, isto é, o objeto que permite retomá-la. O bloco inicia a operação com um objeto de callback que, ao final da operação, retoma a corrotina: ou devolvendo um valor ([resume]) ou fazendo-a lançar uma exceção ([resumeWithException]). O método de callback não faz mais nada: toda a lógica do cliente permanece na corrotina;
  • linhas 104–107: a operação de leitura, também convertida em uma função de suspensão que retorna o número de bytes lidos;
  • o fim dos resultados mostra que a corrotina exibe na thread [main], tanto antes quanto depois das duas suspensões: o método de callback, executado por uma [InnocuousThread], retoma a continuação, mas esta é redirecionada para a thread [runBlocking]. Veremos na seção sobre dispatchers como é escolhida a thread que executa o restante de uma corrotina.

É importante compreender esse mecanismo, pois ele vale para todas as corrotinas: uma corrotina suspensa é uma continuação pendente, e uma continuação nada mais é que um método de callback, mas um que o próprio compilador gera a partir do restante do código. É raro precisar escrever você mesmo funções como [connectTo]: a biblioteca kotlinx.coroutines e outras bibliotecas Kotlin fornecem funções de suspensão para a maioria das operações. Mas, se você precisar usar uma API que só oferece métodos de callback, [suspendCancellableCoroutine] permite transformá-la em poucas linhas.

9.2. Operações futuras: CompletableFuture e Deferred

9.2.1. O CompletableFuture visto do Kotlin

Um [Future<T>] (interface do pacote [java.util.concurrent], Java 5) é um objeto que representa o resultado, do tipo [T], de uma operação em andamento ou já concluída. Já o encontramos no capítulo anterior: é isso que o método [submit] de um executor retorna. É possível consultá-lo (terminou? teve sucesso?), cancelá-lo ([cancel]) e esperar seu resultado ([get]), mas nada além disso: a única maneira de usar o resultado é bloquear uma thread até que ele esteja disponível.

A classe [CompletableFuture<T>] (Java 8) implementa [Future<T>] e acrescenta dois recursos essenciais:

  • é possível concluí-lo você mesmo, seja com um resultado ([complete]), seja com uma exceção ([completeExceptionally]);
  • é possível associar a ele uma etapa de processamento posterior, isto é, uma função que será executada quando o resultado estiver disponível ([thenApply], [thenAccept], [thenCompose]…), e que produz um novo [CompletableFuture]. Isso permite construir cadeias de operações sem que nenhuma thread precise esperar.

Um [CompletableFuture] não é uma thread. Ele pode representar um processamento executado por uma thread de um executor (como é o caso dos criados por [supplyAsync]), mas muitos não são executados por nenhuma thread: aquele retornado pelo método [sendAsync] do cliente HTTP do JDK é concluído quando a resposta do servidor chega. Ele é uma promessa de resultado.

Os programadores Kotlin encontram [CompletableFuture] toda vez que usam uma biblioteca Java assíncrona: o cliente HTTP do JDK, certos drivers de banco de dados, clientes de serviços de nuvem etc. Eles precisam saber lidar com eles e, acima de tudo, como ligá-los às corrotinas. O programa [Async03.kt] é uma versão Kotlin do programa Java que demonstrava as principais maneiras de criar, consultar e esperar um [CompletableFuture]:

// CompletableFutures vistos do Kotlin: criação, espera, estado, resultado, continuação
package async03

import java.util.concurrent.CompletableFuture
import java.util.concurrent.CompletionException
import java.util.concurrent.ExecutionException
import java.util.concurrent.TimeUnit

fun main() {
    // 1 - supplyAsync entrega um processamento a um executor e devolve um CompletableFuture<T>
    val f1: CompletableFuture<Long> = CompletableFuture.supplyAsync {
        // um cálculo de algumas décimas de segundo
        var sum = 0L
        for (i in 1..200_000_000) {
            sum += i % 7
        }
        sum
    }
    println("f1 started, state: ${f1.state()}")
    // join() espera o fim do processamento, bloqueando a thread atual, e devolve seu resultado
    val result = f1.join()
    println("f1 finished, state: ${f1.state()}, result: $result")

    // 2 - um CompletableFuture concluído por um timer após 300 ms, sem ocupar uma thread
    val f2 = CompletableFuture<Unit>().completeOnTimeout(Unit, 300, TimeUnit.MILLISECONDS)
    println("f2 started, state: ${f2.state()}")
    f2.join()
    println("f2 finished, state: ${f2.state()}")

    // 3 - CompletableFutures já concluídos, com sucesso ou com falha
    val f3 = CompletableFuture.completedFuture(42)
    val f4 = CompletableFuture.failedFuture<Int>(IllegalStateException("breakdown"))
    println("f3: state ${f3.state()}, result ${f3.resultNow()} ; " +
            "f4: state ${f4.state()}, exception ${f4.exceptionNow()}")

    // 4 - um processamento que falha: join() lança uma CompletionException que encapsula sua exceção
    val f5 = CompletableFuture.supplyAsync { "abc".toInt() }
    try {
        f5.join()
    } catch (e: CompletionException) {
        println("f5: state ${f5.state()}, join() throws ${e.javaClass.simpleName} containing ${e.cause}")
    }

    // 5 - get(), herdado da interface Future, encapsula a exceção em uma ExecutionException
    try {
        f5.get()
    } catch (e: ExecutionException) {
        println("f5: get() throws ${e.javaClass.simpleName} containing ${e.cause?.javaClass?.simpleName}")
    }

    // 6 - uma continuação: o que deverá ser feito quando o CompletableFuture for concluído
    val f6: CompletableFuture<Int> = f2.thenApply { 2 * 21 }
    val f7: CompletableFuture<Void> = f6.thenAccept { value ->
        println("f7: the continuation received $value")
    }
    f7.join()

    // 7 - isDone, isCompletedExceptionally, isCancelled
    println("f1: isDone=${f1.isDone}, f5: isDone=${f5.isDone}, " +
            "isCompletedExceptionally=${f5.isCompletedExceptionally}, isCancelled=${f5.isCancelled}")
}

Resultados:

> gradlew -q run -Pmain=async03.Async03Kt
f1 started, state: RUNNING
f1 finished, state: SUCCESS, result: 599999998
f2 started, state: RUNNING
f2 finished, state: SUCCESS
f3: state SUCCESS, result 42 ; f4: state FAILED, exception java.lang.IllegalStateException: breakdown
f5: state FAILED, join() throws CompletionException containing java.lang.NumberFormatException: For input string: "abc"
f5: get() throws ExecutionException containing NumberFormatException
f7: the continuation received 42
f1: isDone=true, f5: isDone=true, isCompletedExceptionally=true, isCancelled=false

Comentários:

  • Linhas 10–17: [CompletableFuture.supplyAsync(supplier)] passa uma função sem parâmetros (um [Supplier<T>] do Java) a um executor e retorna imediatamente um [CompletableFuture<T>] que representa sua execução. Graças à conversão SAM (Capítulo 7), uma lambda do Kotlin é passada a ele, colocada fora dos parênteses; sua última expressão, [sum], é o resultado. Sem um executor explícito, é o pool compartilhado da JVM, [ForkJoinPool.commonPool()], que executa a função;
  • linha 19: o método [state()] (Java 19) retorna o estado da operação: [RUNNING] (em andamento), [SUCCESS] (concluída com sucesso), [FAILED] (concluída com uma exceção) ou [CANCELLED] (cancelada). Essas são as constantes da enumeração [Future.State];
  • linha 21: [join()] espera a operação terminar e retorna seu resultado. Trata-se de uma espera bloqueante: a thread atual fica suspensa (aqui, a thread principal, o que não atrapalha em um pequeno programa de console);
  • linhas 24–28: um [CompletableFuture] criado “em andamento” pelo seu construtor e concluído por um temporizador após 300 ms ([completeOnTimeout], Java 9): é o equivalente assíncrono de [Thread.sleep(300)]. Em Java, uma operação sem resultado tem o tipo [CompletableFuture<Void>]; em Kotlin, é possível escrever [CompletableFuture<Unit>], cujo único valor é [Unit];
  • linhas 30–34: [completedFuture(42)] retorna um [CompletableFuture] já concluído cujo resultado é 42, e [failedFuture(exception)] retorna um [CompletableFuture] que já falhou; o tipo do resultado deste último não pode ser inferido a partir de seu argumento, por isso é especificado entre colchetes angulares: [failedFuture<Int>(...)]. [resultNow()] e [exceptionNow()] (Java 19) retornam imediatamente o resultado ou a exceção de uma operação concluída, sem esperar;
  • Linhas 36–41: uma operação cuja função lança uma exceção termina no estado [FAILED]. A exceção é armazenada no [CompletableFuture], e [join()] dispara uma [CompletionException] cuja causa ([cause], o método [getCause()] tratado como propriedade) é a exceção original, neste caso uma [NumberFormatException] lançada por ["abc".toInt()];
  • linhas 44–48: [get()], o método herdado da interface [Future], também espera de forma bloqueante, mas encapsula a exceção em uma [ExecutionException]. Em Java, esta é uma exceção verificada, que o método [main] deveria capturar ou declarar, assim como a [InterruptedException] que [get()] pode lançar. O Kotlin não tem exceções verificadas: você intercepta apenas as que lhe interessam, e nada mais;
  • linhas 51–56: a continuação. [f2.thenApply { 2 * 21 }] retorna um novo [CompletableFuture] que será concluído com o resultado da função quando [f2] for concluído: isso produz um [CompletableFuture<Int>]. [thenAccept] associa uma função que consome o resultado sem produzir outro e retorna um [CompletableFuture<Void>] (este é um método Java: seu tipo de retorno é [Void], que o Kotlin não transforma em [Unit]);
  • linhas 58–60: os métodos booleanos [isDone()] (concluído, independentemente de como), [isCompletedExceptionally()] (concluído com uma exceção ou cancelado) e [isCancelled()] (cancelado): o Kotlin os representa como propriedades: [isDone], [isCompletedExceptionally] e [isCancelled].

O curso de Java dedicou então várias páginas à composição de [CompletableFuture]: [thenCompose], [thenCombine], [allOf], [anyOf], [exceptionally], [handle], [orTimeout]… Em Kotlin, quase nunca é preciso usar esses métodos: basta esperar o [CompletableFuture] em uma corrotina, com a função de suspensão [await()], e escrever o restante como código comum. A tabela a seguir compara os métodos de [CompletableFuture] com seus equivalentes em corrotinas (todas essas funções são tratadas neste capítulo):

[CompletableFuture]
corrotinas
[supplyAsync(f)], [runAsync(r)]
[async { … }] (retorna um [Deferred<T>]), [launch { … }] (retorna um [Job])
[completedFuture(v)], [complete(v)]
um simples valor; [CompletableDeferred] para concluir uma operação manualmente
[thenApply(f)], [thenAccept(c)], [thenRun(r)]
[val v = operation()] seguido do restante do código
[thenCompose(f)]
duas chamadas consecutivas a funções de suspensão
[thenCombine(other, f)], [allOf(...)]
[async], seguido de [await] e [awaitAll]
[anyOf(...)]
[select]
[exceptionally(f)], [handle(f)], [whenComplete(c)]
[try / catch / finally]
[orTimeout(...)], [completeOnTimeout(...)]
[withTimeout], [withTimeoutOrNull]
[cancel]
[cancel], que realmente encerra a operação (reversão cooperativa)
[join()], [get()]
[await()], [join()]: esperas que suspendem a corrotina em vez de bloquear a thread

9.2.2. Deferreds

O equivalente em corrotinas de um [CompletableFuture<T>] é a interface [Deferred<T>] (“diferido”) da kotlinx.coroutines: o resultado futuro de uma corrotina. Ele é obtido iniciando-se uma corrotina com a função [async] e esperando seu resultado com a função de suspensão [await()]. Um [Deferred<T>] é um caso particular de [Job], a interface que representa uma corrotina em execução ou já terminada, sem resultado; um *[Job]* é obtido iniciando-se uma corrotina com a função *[launch]*, e esperando seu término com a função de suspensão *[join()]*.

O programa [Async04.kt] demonstra o [Deferred], o [Job] e a passagem do primeiro para o [CompletableFuture] e vice-versa:

// Deferreds: o resultado futuro de uma corrotina; passando de Deferred para CompletableFuture
package async04

import kotlinx.coroutines.Deferred
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.Job
import kotlinx.coroutines.async
import kotlinx.coroutines.delay
import kotlinx.coroutines.future.asCompletableFuture
import kotlinx.coroutines.future.await
import kotlinx.coroutines.future.future
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.supervisorScope
import java.util.concurrent.CompletableFuture

fun main() = runBlocking {
    // 1 - async lança uma corrotina e devolve imediatamente um Deferred<T>
    val d1: Deferred<Long> = async(Dispatchers.Default) {
        // o mesmo cálculo de algumas décimas de segundo
        var sum = 0L
        for (i in 1..200_000_000) {
            sum += i % 7
        }
        sum
    }
    println("d1 started: ${state(d1)}")
    // await() suspende a corrotina atual até o resultado, sem bloquear sua thread
    val result = d1.await()
    println("d1 finished: ${state(d1)}, result: $result")

    // 2 - uma corrotina que "espera" 300 ms: delay a suspende, nenhuma thread é ocupada
    val d2: Deferred<String> = async {
        delay(300)
        "end of the delay"
    }
    println("d2 started: ${state(d2)}")
    println("d2 finished: ${d2.await()}")

    // 3 - launch lança uma corrotina sem resultado e devolve um Job; join() espera o fim dela
    val job: Job = launch {
        delay(100)
        println("job: work finished")
    }
    job.join()
    println("job: ${state(job)}")

    // 4 - um processamento que falha: await() relança a exceção original, sem encapsulamento
    // (supervisorScope impede que a falha se propague ao programa: veja a seção sobre exceções)
    supervisorScope {
        val d4 = async { "abc".toInt() }
        try {
            d4.await()
        } catch (e: NumberFormatException) {
            println("d4: ${state(d4)}, await() throws ${e.javaClass.simpleName} : ${e.message}")
        }
    }

    // 5 - um CompletableFuture pode ser aguardado por uma corrotina: await() suspende sem bloquear
    val f5: CompletableFuture<Int> = CompletableFuture.supplyAsync { 6 * 7 }
    println("f5: CompletableFuture awaited by a coroutine: ${f5.await()}")

    // 6 - e um Deferred pode ser apresentado como um CompletableFuture, para código Java por exemplo
    val f6: CompletableFuture<Long> = d1.asCompletableFuture()
    println("f6: Deferred seen as a CompletableFuture: state ${f6.state()}, result ${f6.resultNow()}")
    // future { } lança uma corrotina e devolve diretamente um CompletableFuture
    val f7: CompletableFuture<String> = future {
        delay(100)
        "result of a coroutine"
    }
    println("f7: ${f7.thenApply { it.uppercase() }.await()}")
}

// o estado de um Job (um Deferred é um Job que carrega um resultado)
fun state(job: Job) = "isActive=${job.isActive}, isCompleted=${job.isCompleted}, isCancelled=${job.isCancelled}"

Resultados:

> gradlew -q run -Pmain=async04.Async04Kt
d1 started: isActive=true, isCompleted=false, isCancelled=false
d1 finished: isActive=false, isCompleted=true, isCancelled=false, result: 599999998
d2 started: isActive=true, isCompleted=false, isCancelled=false
d2 finished: end of the delay
job: work finished
job: isActive=false, isCompleted=true, isCancelled=false
d4: isActive=false, isCompleted=true, isCancelled=true, await() throws NumberFormatException : For input string: "abc"
f5: CompletableFuture awaited by a coroutine: 42
f6: Deferred seen as a CompletableFuture: state SUCCESS, result 599999998
f7: RESULT OF A COROUTINE

Comentários:

  • Linha 17: a função [main] é uma expressão [runBlocking { … }]. O bloco é executado como uma corrotina pela thread [main], e [runBlocking] só devolve o controle ao final dessa corrotina. É dentro desse bloco que as funções de suspensão ([await], [delay]…) podem ser chamadas e outras corrotinas ([async], [launch]) podem ser iniciadas: o bloco recebe implicitamente um [CoroutineScope] (um escopo de corrotinas), do qual [async] e [launch] são funções de extensão. Voltaremos a isso na seção sobre concorrência estruturada;
  • linhas 18–25: [async] inicia uma nova corrotina que executa o bloco e retorna imediatamente um [Deferred<Long>] que representa seu resultado (a última expressão do bloco). O parâmetro [Dispatchers.Default] faz a corrotina ser executada por um pool de threads dedicado a cálculos: sem ele, a corrotina seria executada pela thread de [runBlocking] e só começaria quando a corrotina principal fosse suspensa pela primeira vez;
  • Linha 27: o estado de uma corrotina é determinado por três propriedades de [Job]: [isActive] (em andamento), [isCompleted] (concluída, independentemente de como) e [isCancelled] (cancelada ou com falha, como veremos adiante). A função [state] (linhas 74–75) as exibe;
  • linha 29: [await()] espera a corrotina terminar e retorna seu resultado. Ao contrário de [join()] em um [CompletableFuture], essa espera não bloqueia a thread: é uma função de suspensão, que suspende a corrotina principal; enquanto isso, a thread [main] fica disponível para outras corrotinas;
  • linhas 32–38: uma corrotina que espera 300 ms com *[delay]* e depois retorna uma string: nenhuma thread fica ocupada durante a espera;
  • linhas 40–46: [launch] inicia uma corrotina que não retorna resultado e devolve um [Job]. [join()] suspende a corrotina principal até que essa corrotina termine. [launch] / [Job] estão para as corrotinas assim como [runAsync] / [CompletableFuture<Void>] estão para o mundo dos [CompletableFuture];
  • Linhas 48–55: uma corrotina que falha. [await()] relança a exceção original, uma [NumberFormatException], sem encapsulá-la em outra exceção: ela é interceptada como se a chamada tivesse sido feita diretamente. O estado exibido mostra que um [Job] com falha tem [isCancelled=true]: para a kotlinx.coroutines, uma falha é uma forma de cancelamento. O bloco [supervisorScope] é necessário aqui por um motivo que veremos na seção sobre exceções: sem ele, a falha de uma corrotina se propagaria para a corrotina que a iniciou e teria encerrado o programa inteiro;
  • Linhas 59–61: a função de extensão [CompletableFuture<T>.await()], do pacote [kotlinx.coroutines.future], espera um [CompletableFuture] suspendendo a corrotina, sem bloquear nenhuma thread. Ela serve de ponte entre as bibliotecas Java assíncronas e as corrotinas: uma chamada [client.sendAsync(request, handler).await()] espera a resposta de um servidor web, como veremos mais adiante neste capítulo. Se o [CompletableFuture] falhar, [await()] lança a exceção original, sem o encapsulamento em [CompletionException];
  • linhas 63–65: inversamente, [asCompletableFuture()] apresenta um [Deferred] como um [CompletableFuture], por exemplo, para passá-lo a um código Java que não suporta corrotinas;
  • linhas 66–71: a função [future { … }] inicia uma corrotina e retorna diretamente um [CompletableFuture]: é assim que se escreve, em Kotlin, usando corrotinas, um método assíncrono destinado a código Java. Na linha 71, esse *[CompletableFuture] é composto com *[thenApply], e depois o resultado é aguardado com *[await()]*.

9.3. Funções de suspensão

9.3.1. suspend, launch, async e await

Em Kotlin, uma operação assíncrona é escrita como uma função de suspensão: uma função comum, declarada com o modificador *[suspend] , que retorna diretamente seu resultado (em vez de um *[CompletableFuture] ou de um *[Deferred]* que o representaria):

  • [suspend fun makeCoffee()] para uma operação que não retorna resultado;
  • [suspend fun countSugars(number: Int): Int] para uma operação que retorna um inteiro.

Uma função de suspensão pode chamar outras funções de suspensão, como [delay], [await] e [join], e é durante essas chamadas que ela pode ser suspensa. Ela só pode ser chamada por outra função de suspensão ou a partir de uma corrotina (o corpo de um [runBlocking], de um [launch] ou de um [async]); o compilador impõe isso. Essa é a única restrição: dentro dela, escreve-se código comum, com laços, [if], [try / catch] e variáveis locais.

Uma chamada a uma função de suspensão não inclui nenhuma palavra-chave: onde o C# escreve [await MakeCoffeeAsync()], o Kotlin escreve [makeCoffee()]. E essa chamada é sequencial: a linha seguinte só é executada depois que a função chamada termina. Para executar várias operações em paralelo, é preciso indicá-lo explicitamente, iniciando novas corrotinas com [launch] ou *[async]*. Essa é uma escolha deliberada dos projetistas do Kotlin: o código sequencial é a norma, portanto deve ser o mais simples de escrever; a concorrência deve ser explícita.

O tutorial de Java preparava café e contava cubos de açúcar, primeiro com [CompletableFuture] encadeados com [thenRun] e [thenCompose], depois com código bloqueante executado por threads virtuais. O programa [Async05.kt] prepara o mesmo café usando funções de suspensão:

// café com funções suspensas: funções comuns, que são lidas de cima para baixo
package async05

import kotlinx.coroutines.Deferred
import kotlinx.coroutines.Job
import kotlinx.coroutines.async
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

var start = System.nanoTime()

fun main() = runBlocking {
    // 1 - as duas operações são lançadas em duas corrotinas e depois aguardadas
    display("launching makeCoffee")
    val preparation: Job = launch { makeCoffee() }
    display("makeCoffee is launched: the program continues")
    display("launching countSugars")
    val counting: Deferred<Int> = async { countSugars(3) }
    display("countSugars is launched")
    // agora esperamos as duas operações: a corrotina principal é suspensa
    preparation.join()
    val nbSugars = counting.await()
    display("coffee ready, with $nbSugars sugar(s)")

    // 2 - as mesmas funções chamadas diretamente: elas executam uma após a outra
    start = System.nanoTime()
    display("direct calls")
    makeCoffee()
    val number = countSugars(3)
    display("coffee ready, with $number sugar(s)")
}

// uma função suspensa que não devolve resultado
suspend fun makeCoffee() {
    display("  coffee: the machine is heating up")
    // delay suspende a corrotina sem bloquear a thread que a executa
    delay(1000)
    display("  coffee: the machine is pouring the coffee")
    delay(500)
    display("  coffee: finished")
}

// uma função suspensa que devolve um inteiro
suspend fun countSugars(number: Int): Int {
    for (i in 1..number) {
        delay(200)
        display("  sugar no. $i")
    }
    return number
}

// exibição com o tempo decorrido desde [start] e o nome da thread
fun display(message: String) {
    val elapsed = (System.nanoTime() - start) / 1_000_000
    println("%5d ms [%s] %s".format(elapsed, Thread.currentThread().name, message))
}

Resultados:

> gradlew -q run -Pmain=async05.Async05Kt
   47 ms [main] launching makeCoffee
   62 ms [main] makeCoffee is launched: the program continues
   62 ms [main] launching countSugars
   65 ms [main] countSugars is launched
   67 ms [main]   coffee: the machine is heating up
  281 ms [main]   sugar no. 1
  482 ms [main]   sugar no. 2
  683 ms [main]   sugar no. 3
 1068 ms [main]   coffee: the machine is pouring the coffee
 1569 ms [main]   coffee: finished
 1571 ms [main] coffee ready, with 3 sugar(s)
    0 ms [main] direct calls
    0 ms [main]   coffee: the machine is heating up
 1000 ms [main]   coffee: the machine is pouring the coffee
 1501 ms [main]   coffee: finished
 1702 ms [main]   sugar no. 1
 1902 ms [main]   sugar no. 2
 2103 ms [main]   sugar no. 3
 2104 ms [main] coffee ready, with 3 sugar(s)

Comentários:

  • Linhas 34–41: uma operação sem resultado escrita como função comum: uma instrução de impressão, uma espera de um segundo, uma instrução de impressão, uma espera de meio segundo, uma instrução de impressão. [delay] é a função de suspensão da kotlinx.coroutines, que espera o atraso especificado (em milissegundos ou na forma de uma duração [kotlin.time.Duration]: [delay(1.seconds)]) suspendendo a corrotina. Isso equivale ao método [delay] do programa Java, que retornava um [CompletableFuture] concluído por um temporizador; mas aqui o restante da função não precisa ser escrito em uma continuação: ele simplesmente segue a chamada;
  • linhas 44–50: uma operação que retorna um inteiro. O laço é um laço de verdade, que espera a cada iteração: essa é a única diferença em relação à versão Java com [CompletableFuture], em que o laço construía uma cadeia de [thenCompose] em vez de executar iterações (e em que era necessária uma variável [number], cópia de [i], para a lambda);
  • linha 16: [launch] inicia uma nova corrotina que executa [makeCoffee()] e retorna imediatamente um [Job];
  • linha 19: [async] inicia uma nova corrotina que executa [countSugars(3)] e retorna imediatamente um [Deferred<Int>];
  • linhas 22–23: a corrotina principal espera as duas operações; ela fica suspensa durante essas esperas;
  • As linhas 2 a 12 da saída mostram a execução: o café fica pronto após 1,5 segundo, a duração da mais longa das duas operações, e os sachês de açúcar foram contados enquanto a máquina esquentava. Mas elas também mostram uma diferença em relação aos programas Java: a máquina só começa a esquentar (linha 6) depois da última instrução de impressão do programa principal (linha 5). Todas as corrotinas do programa são executadas por uma única thread, [main], que pertence a [runBlocking]: [launch] e [async] não executam imediatamente a corrotina que criam; em vez disso, colocam-na na fila da thread, que a executará quando ficar livre, isto é, quando a corrotina principal se suspender (linha 22). Isso se chama multitarefa cooperativa: uma corrotina mantém a thread até se suspender;
  • linhas 26–31: as mesmas funções chamadas diretamente, sem iniciar uma corrotina. Cada chamada termina antes que a seguinte comece: o café é preparado (1,5 segundo) e depois os cubos de açúcar são contados (0,6 segundo), num total de 2,1 segundos (linhas 13–20 dos resultados). Essa é a abordagem correta quando uma operação depende do resultado da anterior;
  • linha 54: cada saída mostra o tempo decorrido e a thread que a executa: é sempre [main].

Vemos a mesma qualidade da versão Java com threads virtuais: as funções são funções comuns, que se leem de cima para baixo; a decisão de executá-las sequencialmente (chamada direta) ou concorrentemente ([launch], [async]) é tomada no momento da chamada. No entanto, ao contrário das threads virtuais, uma única thread bastou para o programa inteiro, e não foi a JVM que liberou a thread durante as esperas: foram as próprias funções de suspensão.

9.3.2. delay e Thread.sleep

Uma corrotina libera sua thread somente quando se suspende, isto é, quando chama uma função de suspensão que está esperando. Se ela chamar uma função bloqueante ([Thread.sleep], uma leitura de arquivo ou de socket com as classes de [java.io], uma requisição JDBC…), ela bloqueia a thread que a executa, e todas as corrotinas que dependem dessa thread ficam em espera. O programa [Async06.kt] ilustra a diferença:

// delay suspende a corrotina, Thread.sleep bloqueia a thread
package async06

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

var start = 0L

fun main() {
    // 1 - duas corrotinas que esperam com delay: elas compartilham a única thread [main]
    start = System.nanoTime()
    runBlocking {
        launch { workWithDelay("A") }
        launch { workWithDelay("B") }
    } // runBlocking retorna quando suas duas corrotinas terminam
    display("1 - end, with delay")

    // 2 - as mesmas corrotinas com Thread.sleep: a thread [main] fica bloqueada a cada espera
    start = System.nanoTime()
    runBlocking {
        launch { workWithSleep("A") }
        launch { workWithSleep("B") }
    }
    display("2 - end, with Thread.sleep")

    // 3 - Thread.sleep no dispatcher IO: cada corrotina bloqueia uma thread do pool IO
    start = System.nanoTime()
    runBlocking {
        launch(Dispatchers.IO) { workWithSleep("A") }
        launch(Dispatchers.IO) { workWithSleep("B") }
    }
    display("3 - end, with Thread.sleep on Dispatchers.IO")
}

// três etapas separadas por esperas de 100 ms que suspendem a corrotina
suspend fun workWithDelay(name: String) {
    for (i in 1..3) {
        display("  $name$i")
        delay(100)
    }
}

// três etapas separadas por esperas de 100 ms que bloqueiam a thread
fun workWithSleep(name: String) {
    for (i in 1..3) {
        display("  $name$i")
        Thread.sleep(100)
    }
}

// exibição com o tempo decorrido desde [start] e o nome da thread
fun display(message: String) {
    val elapsed = (System.nanoTime() - start) / 1_000_000
    println("%5d ms [%s] %s".format(elapsed, Thread.currentThread().name, message))
}

Resultados:

> gradlew -q run -Pmain=async06.Async06Kt
   67 ms [main]   A1
   97 ms [main]   B1
  193 ms [main]   A2
  198 ms [main]   B2
  294 ms [main]   A3
  298 ms [main]   B3
  399 ms [main] 1 - end, with delay
    1 ms [main]   A1
  101 ms [main]   A2
  202 ms [main]   A3
  303 ms [main]   B1
  403 ms [main]   B2
  504 ms [main]   B3
  604 ms [main] 2 - end, with Thread.sleep
   10 ms [DefaultDispatcher-worker-1]   A1
   10 ms [DefaultDispatcher-worker-2]   B1
  112 ms [DefaultDispatcher-worker-1]   A2
  112 ms [DefaultDispatcher-worker-2]   B2
  213 ms [DefaultDispatcher-worker-1]   A3
  213 ms [DefaultDispatcher-worker-2]   B3
  314 ms [main] 3 - end, with Thread.sleep on Dispatchers.IO

Comentários:

  • Linhas 12–18: duas corrotinas iniciadas em um *[runBlocking], cada uma das quais executa três etapas separadas por *[delay(100)]*. Elas compartilham a thread *[main] : enquanto uma espera, a outra trabalha; as etapas se alternam (A1, B1, A2, B2…) e os períodos de espera das duas corrotinas se sobrepõem: o processo inteiro leva cerca de 300 ms, mais o tempo de carregamento das classes da biblioteca nesse primeiro uso (linha 8 dos resultados). A função [runBlocking] só devolve o controle quando as duas corrotinas que ela iniciou terminam: não é preciso escrever código para esperá-las;
  • linhas 20–26: as mesmas corrotinas, esperando com [Thread.sleep]. Cada espera bloqueia a única thread [main]: a corrotina B só pode começar depois que A termina, e o processo inteiro leva 600 ms (linhas 9–15). As duas corrotinas deixam de ser verdadeiramente corrotinas: elas se executam uma após a outra;
  • linhas 28–34: as corrotinas que contêm código bloqueante são repassadas a outro grupo de threads, o dispatcher [Dispatchers.IO], passando-o como parâmetro a [launch]. Cada uma bloqueia então sua própria thread; elas rodam simultaneamente, e o processo inteiro volta a levar 300 ms (linhas 16–22). Esta é a abordagem padrão quando é preciso chamar código bloqueante a partir de corrotinas (como uma biblioteca que não oferece funções de suspensão, por exemplo, o JDBC); mas isso acarreta o custo de uma thread de sistema por operação em andamento. As threads desse dispatcher se chamam [DefaultDispatcher-worker-N]: veremos o motivo na seção sobre dispatchers;
  • linhas 37–41: [workWithDelay] chama [delay]: esta é uma função de suspensão;
  • linhas 45–49: [workWithSleep] não chama nenhuma função de suspensão: é uma função comum. O compilador permite que ela seja chamada a partir de uma corrotina, mas o IntelliJ e o IDEA sinalizam as chamadas a funções bloqueantes conhecidas ([Thread.sleep], as operações de E/S de [java.io]) colocadas dentro de uma função de suspensão ou de uma corrotina (“Possibly blocking call in non-blocking context”).

Daí a primeira regra da programação com corrotinas: uma função de suspensão nunca deve bloquear sua thread. Se precisar chamar código bloqueante, ela o delega a um dispatcher concebido para isso ([Dispatchers.IO], ou um dispatcher baseado em threads virtuais), com [withContext], que veremos em breve.

9.3.3. O que o compilador faz: continuações e máquinas de estados

Como uma função de suspensão consegue fazer uma pausa no meio de um laço, liberar sua thread e depois retomar mais tarde no mesmo ponto, com os mesmos valores de variáveis locais, possivelmente em outra thread? O curso de Java explicou que, para uma thread virtual, é a JVM que faz esse trabalho: ela copia a pilha de chamadas da thread virtual para o heap e a restaura ali mais tarde. A JVM não sabe nada sobre as corrotinas do Kotlin: quem faz o trabalho é o compilador , transformando cada função de suspensão. Ele o faz em duas etapas.

Primeira etapa: a continuação se torna um parâmetro. Cada função [suspend] recebe, no bytecode, um parâmetro adicional do tipo [Continuation<T>] (uma interface do pacote [kotlin.coroutines] da biblioteca padrão), em que [T] é o tipo do valor de retorno da função. Uma continuação representa “a próxima etapa do cálculo”: o que fazer com o resultado da função. Ela tem um método [resumeWith(result)], que retoma a execução com um resultado ou uma exceção (as funções de extensão [resume(value)] e [resumeWithException(e)] o chamam), e uma propriedade [context], o contexto da corrotina (voltaremos a isso). O tipo de retorno da função se torna [Any?] ([Object] na JVM): a função retorna ou seu resultado, se conseguiu terminar sem esperar, ou um valor especial, [COROUTINE_SUSPENDED], que significa “estou suspensa; minha continuação será retomada mais tarde”. Este é o “estilo de passagem de continuação” (CPS, continuation-passing style).

Segunda etapa: o corpo da função se torna uma máquina de estados. Cada chamada a uma função de suspensão dentro do corpo é um potencial ponto de suspensão. O compilador numera esses pontos (o número é chamado de [label]) e armazena o número do próximo ponto de retomada e as variáveis locais que precisam sobreviver a uma suspensão em um objeto de continuação específico da função. O corpo da função se torna um [when] sobre esse número: ele é executado uma vez no início (label 0) e depois uma vez a cada retomada, e o programa salta diretamente para o ponto em que parou.

O programa [Async07.kt] demonstra tudo isso. Ele usa apenas a biblioteca padrão do Kotlin (não a kotlinx.coroutines), para que possamos ver os mecanismos básicos: ele escreve por conta própria o equivalente de [delay] e inicia uma corrotina por si mesmo.

// o que o compilador faz: uma função suspensa recebe uma continuação
// (este programa usa apenas a biblioteca padrão do Kotlin, não kotlinx.coroutines)
package async07

import java.util.concurrent.CountDownLatch
import java.util.concurrent.Executors
import java.util.concurrent.TimeUnit
import kotlin.coroutines.Continuation
import kotlin.coroutines.EmptyCoroutineContext
import kotlin.coroutines.resume
import kotlin.coroutines.startCoroutine
import kotlin.coroutines.suspendCoroutine

// um timer: uma thread que executa ações após um atraso
val timer = Executors.newSingleThreadScheduledExecutor { action -> Thread(action, "timer") }

// o equivalente a delay, escrito com suspendCoroutine
suspend fun pause(ms: Long): Unit = suspendCoroutine { continuation ->
    display("    pause($ms): the coroutine is suspended")
    // o timer retomará a corrotina após o atraso
    timer.schedule({ continuation.resume(Unit) }, ms, TimeUnit.MILLISECONDS)
}

// uma função suspensa com dois pontos de suspensão e variáveis locais
suspend fun addUp(a: Int, b: Int): Int {
    display("  addUp($a, $b): start")
    val x = a * 10
    pause(300)
    display("  addUp: resumed after the 1st pause, x = $x")
    val y = b * 10
    pause(200)
    display("  addUp: resumed after the 2nd pause, x + y = ${x + y}")
    return x + y
}

fun main() {
    val end = CountDownLatch(1)
    // a continuação final: o que fazer com o resultado da corrotina
    val next = Continuation<Int>(EmptyCoroutineContext) { result ->
        display("final continuation: result = ${result.getOrThrow()}")
        end.countDown()
    }
    // uma lambda suspensa, iniciada como corrotina com a continuação final
    val coroutine: suspend () -> Int = { addUp(4, 5) }
    display("starting the coroutine")
    coroutine.startCoroutine(next)
    display("startCoroutine has returned")
    // a thread principal espera o sinal da continuação final
    end.await()
    timer.shutdown()
}

// exibição prefixada pelo nome da thread que a executa
fun display(message: String) = println("[${Thread.currentThread().name}] $message")

Resultados:

1
2
3
4
5
6
7
8
9
> gradlew -q run -Pmain=async07.Async07Kt
[main] starting the coroutine
[main]   addUp(4, 5): start
[main]     pause(300): the coroutine is suspended
[main] startCoroutine has returned
[timer]   addUp: resumed after the 1st pause, x = 40
[timer]     pause(200): the coroutine is suspended
[timer]   addUp: resumed after the 2nd pause, x + y = 90
[timer] final continuation: result = 90

Comentários:

  • linha 15: um temporizador, isto é, um executor de thread única chamado [timer], capaz de executar uma ação após um atraso ([ScheduledExecutorService], Capítulo 8);
  • linhas 17–21: a função de suspensão [pause], nosso próprio [delay]. Ela usa a função [suspendCoroutine] da biblioteca padrão (da qual [suspendCancellableCoroutine], encontrada em [Async02.kt], é a versão cancelável da kotlinx.coroutines): [suspendCoroutine] passa ao bloco a continuação da corrotina atual e depois a suspende. O bloco instrui o temporizador a retomar a continuação após o atraso especificado, com o valor [Unit];
  • linhas 24–33: uma função de suspensão com dois pontos de suspensão (as duas chamadas a [pause]) e variáveis locais ([a], [b], [x], [y]) que precisam sobreviver às suspensões;
  • linhas 39–46: uma corrotina é iniciada manualmente. A função [Continuation(context) { … }] cria uma continuação a partir de um bloco que recebe o resultado, do tipo [Result<Int>] (um resultado ou uma exceção; [getOrThrow()] retorna o primeiro ou lança a segunda): esta é a continuação final, que exibe o resultado e notifica a thread principal. O contexto vazio, [EmptyCoroutineContext], significa que nada específico é solicitado, em particular nenhum dispatcher. A função de extensão [startCoroutine] inicia uma lambda de suspensão ([suspend () -> Int]) como uma corrotina, com a continuação final;
  • os resultados mostram a execução: [startCoroutine] executa a função [addUp] na thread [main] até o primeiro ponto de suspensão (linhas 3 e 4) e depois devolve o controle (linha 5): a função retornou [COROUTINE_SUSPENDED]. 300 ms depois, a thread [timer] retoma a execução: a função [addUp] continua logo após a primeira chamada a [pause], com o valor de [x] intacto (linha 6), em uma thread diferente daquela em que começou. Em seguida vêm a segunda pausa, o fim da função e a continuação final, que recebe o resultado 90 (linha 9). As corrotinas da kotlinx.coroutines não fazem nada além disso; os dispatchers apenas especificam qual thread executa cada continuação.

Vamos ver o que o compilador produziu. A ferramenta [javap] do JDK exibe os membros de uma classe compilada. O Gradle coloca as classes compiladas na pasta [build/classes/kotlin/main] do projeto:

> javap -p -cp build/classes/kotlin/main async07.Async07Kt
Compiled from "Async07.kt"
public final class async07.Async07Kt {
  private static final java.util.concurrent.ScheduledExecutorService timer;
  public static final java.util.concurrent.ScheduledExecutorService getTimer();
  public static final java.lang.Object pause(long, kotlin.coroutines.Continuation<? super kotlin.Unit>);
  public static final java.lang.Object addUp(int, int, kotlin.coroutines.Continuation<? super java.lang.Integer>);
  public static final void main();
  public static final void display(java.lang.String);
  public static void main(java.lang.String[]);
  private static final java.lang.Thread timer$lambda$0(java.lang.Runnable);
  static {};
}
  • Linhas 6 e 7: as funções [pause] e [addUp] receberam um parâmetro final do tipo [Continuation], e seu tipo de retorno passou a ser [Object]. O parâmetro de continuação de [addUp] tem o mesmo tipo que seu resultado: [Continuation<? super Integer>]. Do ponto de vista do Java, [addUp] é um método comum que pode ser chamado passando-lhe uma continuação (é, aliás, assim que o código Java pode chamar uma função de suspensão, embora com alguma dificuldade);
  • Linha 8: a função [main] sem parâmetros, ao lado do método [main(String[])] que o compilador adiciona para a JVM (linha 10), como vimos no Capítulo 3.

O compilador também gerou uma classe chamada [Async07Kt$addUp$1]: é o objeto de continuação da função [addUp]:

> javap -p -cp build/classes/kotlin/main "async07.Async07Kt$addUp$1"
Compiled from "Async07.kt"
final class async07.Async07Kt$addUp$1 extends kotlin.coroutines.jvm.internal.ContinuationImpl {
  int I$0;
  int I$1;
  int I$2;
  int I$3;
  java.lang.Object result;
  int label;
  async07.Async07Kt$addUp$1(kotlin.coroutines.Continuation<? super async07.Async07Kt$addUp$1>);
  public final java.lang.Object invokeSuspend(java.lang.Object);
}
  • linha 3: a classe deriva de [ContinuationImpl], uma classe interna da biblioteca padrão que implementa [Continuation];
  • Linhas 4 a 7: quatro campos inteiros, [I$0] a [I$3], nos quais a função armazena suas variáveis locais [a], [b], [x], e [y] antes de cada suspensão;
  • linha 8: [result] recebe o resultado (ou a exceção) com o qual a execução é retomada;
  • linha 9: [label], o número do próximo ponto de retomada;
  • linha 11: [invokeSuspend], o método chamado na retomada, que simplesmente chama a função [addUp], passando-lhe este objeto de continuação.

Por fim, a opção [-c] de [javap] exibe o bytecode dos métodos. Aqui estão dois trechos do bytecode de [addUp] (o comando [javap -c -p -cp build/classes/kotlin/main async07.Async07Kt] exibe o bytecode completo):

        56: invokestatic  #71                 // Method kotlin/coroutines/intrinsics/IntrinsicsKt.getCOROUTINE_SUSPENDED:()Ljava/lang/Object;
        59: astore        7
        61: aload         6
        63: getfield      #97                 // Field async07/Async07Kt$addUp$1.label:I
        66: tableswitch   { // 0 to 2
                       0: 92
                       1: 153
                       2: 242
                 default: 295
            }
  • No ponto de entrada da função (antes do trecho), o bytecode recupera o objeto de continuação da função, se for uma retomada, ou cria um, se for a primeira chamada;
  • [getCOROUTINE_SUSPENDED] lê o valor especial [COROUTINE_SUSPENDED], armazenado em uma variável local;
  • [tableswitch] é a instrução da JVM que corresponde a uma operação [when] sobre um inteiro: dependendo do valor do campo [label] (0, 1 ou 2), a execução salta para o início da função (endereço 92), logo após a primeira chamada a [pause] (endereço 153) ou logo após a segunda (endereço 242). Qualquer outro valor resulta em um erro (endereço 295).
       112: ldc2_w        #115                // long 300l
       115: aload         6
       117: aload         6
       119: iload_0
       120: putfield      #119                // Field async07/Async07Kt$addUp$1.I$0:I
       123: aload         6
       125: iload_1
       126: putfield      #122                // Field async07/Async07Kt$addUp$1.I$1:I
       129: aload         6
       131: iload_3
       132: putfield      #125                // Field async07/Async07Kt$addUp$1.I$2:I
       135: aload         6
       137: iconst_1
       138: putfield      #97                 // Field async07/Async07Kt$addUp$1.label:I
       141: invokestatic  #127                // Method pause:(JLkotlin/coroutines/Continuation;)Ljava/lang/Object;
       144: dup
       145: aload         7
       147: if_acmpne     178
       150: aload         7
       152: areturn
       153: aload         6
       155: getfield      #125                // Field async07/Async07Kt$addUp$1.I$2:I
       158: istore_3
       159: aload         6
       161: getfield      #122                // Field async07/Async07Kt$addUp$1.I$1:I
       164: istore_1
       165: aload         6
       167: getfield      #119                // Field async07/Async07Kt$addUp$1.I$0:I
       170: istore_0
       171: aload         5
       173: invokestatic  #109                // Method kotlin/ResultKt.throwOnFailure:(Ljava/lang/Object;)V
       176: aload         5
  • endereços 112 a 138: antes da primeira chamada a [pause], a função copia suas variáveis locais [a], [b] e [x] (variáveis 0, 1 e 3 da JVM) para os campos [I$0], [I$1] e [I$2] do objeto de continuação e define [label] como 1;
  • endereço 141: a chamada a [pause(300)], com o objeto de continuação como último parâmetro;
  • endereços 144 a 152: se [pause] retornou [COROUTINE_SUSPENDED], a função, por sua vez, retorna [COROUTINE_SUSPENDED] ao seu chamador ([areturn]): é assim que a suspensão “sobe” pela pilha de chamadas até [startCoroutine], que devolve o controle à thread [main]. Caso contrário, a execução continua diretamente no endereço 178;
  • endereços 153 a 170: ponto de retomada nº 1. A função copia os campos do objeto de continuação para suas variáveis locais e então prossegue como se nada tivesse acontecido.

A pilha de chamadas da JVM nunca é, portanto, preservada: a cada suspensão, todas as funções atualmente suspensas retornam [COROUTINE_SUSPENDED], e seus quadros de pilha desaparecem; o que precisa sobreviver é armazenado nos objetos de continuação, que são encadeados entre si (cada um conhece a continuação de seu chamador). A cada retomada, a cadeia é percorrida em ordem inversa. É o mesmo conceito da “máquina de estados” que o compilador C# cria para um método [async].

Para compreender bem esse mecanismo, o programa [Async08.kt] escreve manualmente, em Kotlin, uma versão simplificada do que o compilador gerou para [pause] e [addUp]:

// a máquina de estados que o compilador gera para uma função suspensa, escrita à mão
// (versão simplificada do que ele produz para a função [addUp] do programa Async07)
package async08

import java.util.concurrent.CountDownLatch
import java.util.concurrent.Executors
import java.util.concurrent.TimeUnit
import kotlin.coroutines.Continuation
import kotlin.coroutines.CoroutineContext
import kotlin.coroutines.EmptyCoroutineContext
import kotlin.coroutines.intrinsics.COROUTINE_SUSPENDED

// um timer: uma thread que executa ações após um atraso
val timer = Executors.newSingleThreadScheduledExecutor { action -> Thread(action, "timer") }

// a função pause "compilada": ela recebe a continuação a retomar e devolve COROUTINE_SUSPENDED
fun pause(ms: Long, continuation: Continuation<Unit>): Any {
    display("    pause($ms): the coroutine is suspended")
    timer.schedule({ continuation.resumeWith(Result.success(Unit)) }, ms, TimeUnit.MILLISECONDS)
    return COROUTINE_SUSPENDED
}

// a continuação de [addUp]: o estado da máquina e as variáveis locais a manter
class AddUpContinuation(val caller: Continuation<Int>, val a: Int, val b: Int) : Continuation<Unit> {
    // o número do próximo ponto de retomada
    var label = 0
    // as variáveis locais que devem sobreviver às suspensões
    var x = 0
    var y = 0
    override val context: CoroutineContext get() = caller.context

    // chamada ao fim de uma pausa: a máquina de estados é reiniciada de onde havia parado
    override fun resumeWith(result: Result<Unit>) {
        val outcome = addUp(this)
        // se a função foi executada até o fim, a continuação do chamador é retomada
        if (outcome !== COROUTINE_SUSPENDED) {
            caller.resumeWith(Result.success(outcome as Int))
        }
    }
}

// a função [addUp] transformada em uma máquina de estados: ela é chamada no início e depois a cada retomada
fun addUp(state: AddUpContinuation): Any {
    while (true) {
        when (state.label) {
            0 -> {
                display("  addUp(${state.a}, ${state.b}): start (label 0)")
                state.x = state.a * 10
                // o próximo ponto de retomada é o nº 1
                state.label = 1
                if (pause(300, state) === COROUTINE_SUSPENDED) return COROUTINE_SUSPENDED
            }
            1 -> {
                display("  addUp: resumed after the 1st pause (label 1), x = ${state.x}")
                state.y = state.b * 10
                state.label = 2
                if (pause(200, state) === COROUTINE_SUSPENDED) return COROUTINE_SUSPENDED
            }
            2 -> {
                display("  addUp: resumed after the 2nd pause (label 2), x + y = ${state.x + state.y}")
                return state.x + state.y
            }
            else -> error("unknown resumption point: ${state.label}")
        }
    }
}

fun main() {
    val end = CountDownLatch(1)
    // a continuação final: o que fazer com o resultado
    val next = Continuation<Int>(EmptyCoroutineContext) { result ->
        display("final continuation: result = ${result.getOrThrow()}")
        end.countDown()
    }
    display("first call of addUp")
    val returned = addUp(AddUpContinuation(next, 4, 5))
    display("addUp returned ${if (returned === COROUTINE_SUSPENDED) "COROUTINE_SUSPENDED" else returned}")
    end.await()
    timer.shutdown()
}

// exibição prefixada pelo nome da thread que a executa
fun display(message: String) = println("[${Thread.currentThread().name}] $message")

Resultados:

1
2
3
4
5
6
7
8
9
> gradlew -q run -Pmain=async08.Async08Kt
[main] first call of addUp
[main]   addUp(4, 5): start (label 0)
[main]     pause(300): the coroutine is suspended
[main] addUp returned COROUTINE_SUSPENDED
[timer]   addUp: resumed after the 1st pause (label 1), x = 40
[timer]     pause(200): the coroutine is suspended
[timer]   addUp: resumed after the 2nd pause (label 2), x + y = 90
[timer] final continuation: result = 90

Comentários:

  • Linhas 16–20: a função [pause] como o compilador a vê: uma função comum (sem [suspend]) que recebe a continuação a retomar, agenda sua retomada e retorna [COROUTINE_SUSPENDED], uma constante do pacote [kotlin.coroutines.intrinsics] da biblioteca padrão;
  • linhas 23–29: o objeto de continuação de [addUp]. Ele conhece a continuação do chamador ([caller]), os parâmetros [a] e [b], o número do próximo ponto de retomada ([label]) e as variáveis locais [x] e [y]. O compilador, por sua vez, também armazena os parâmetros em campos e reutiliza campos genéricos ([I$0]…);
  • linha 30: uma continuação deve fornecer o contexto de sua corrotina; usamos o do chamador;
  • linhas 33–37: a retomada. O timer chama [resumeWith] no fim de uma pausa; o método chama [addUp] novamente com o objeto de continuação, que sabe onde retomar. Se a função é executada até o fim (ela não retorna [COROUTINE_SUSPENDED]), seu resultado é passado à continuação do chamador: é assim que o resultado “volta” de uma função de suspensão para aquela que a chamou;
  • linhas 42–63: a máquina de estados. A chamada de [when] a [state.label] direciona a execução para a seção correta da função. Cada seção termina salvando o próximo ponto de retomada e chamando [pause]: se [pause] retorna [COROUTINE_SUSPENDED], a função também o retorna; caso contrário (uma função de suspensão pode ser executada até o fim sem suspender, por exemplo se o resultado já é conhecido), o laço [while (true)] passa diretamente para a próxima seção. As variáveis locais são lidas e gravadas no objeto de continuação ([state.x], [state.y]);
  • linhas 76–77: a primeira chamada. Os resultados mostram que [addUp] retornou [COROUTINE_SUSPENDED] (linha 5 dos resultados); o restante do processo ocorre na thread [timer], exatamente como em [Async07.kt].

Este programa é incluído apenas para fins ilustrativos: você nunca escreveria esse código por conta própria. No entanto, há duas lições essenciais:

  • uma corrotina suspensa custa apenas seus objetos de continuação — algumas dezenas de bytes por função ativa — em vez de uma pilha de um megabyte como a de uma thread de plataforma: foi isso que tornou possíveis as 100.000 corrotinas de [Async01.kt];
  • a suspensão só é possível em chamadas a funções de suspensão. Uma função comum não pode ser suspensa: se ela bloqueia (como [Thread.sleep]), bloqueia a thread. Essa é a diferença fundamental em relação às threads virtuais, nas quais a JVM pode suspender qualquer código bloqueante escrito em Java. Em contrapartida, as corrotinas não dependem da JVM: o mesmo mecanismo funciona com Kotlin/JS em um navegador de thread única e com Kotlin/Native.

9.3.4. Dispatchers: qual thread executa o restante do código?

Uma corrotina não é uma thread: são necessárias threads para executá-la. O componente que decide qual thread executa uma corrotina — na inicialização e depois a cada retomada — é o seu dispatcher, um elemento do contexto da corrotina. O contexto de uma corrotina ([CoroutineContext]) é um pequeno conjunto de elementos indexados por seu tipo, que são combinados por meio do operador [+]: o dispatcher ([CoroutineDispatcher]), o [Job] da corrotina, seu nome ([CoroutineName]) e seu tratador de exceções ([CoroutineExceptionHandler], que veremos mais adiante)… Um contexto é passado como parâmetro para [launch], [async], [runBlocking], ou [withContext]; a nova corrotina herda os elementos do contexto de seu escopo, exceto aqueles que são substituídos.

O kotlinx.coroutines fornece quatro dispatchers, que são propriedades do objeto [Dispatchers]:

Dispatcher
Threads utilizadas
[Dispatchers.Default]
Um pool de threads para cálculos, com tantas threads quantos forem os processadores (no mínimo duas). É o dispatcher usado quando nenhum é especificado e o escopo não possui um.
[Dispatchers.IO]
Um pool de threads para operações bloqueantes (arquivos, JDBC, sockets bloqueantes), que pode conter até 64 threads (ou mais, se a máquina tiver mais de 64 processadores; a propriedade de sistema [kotlinx.coroutines.io.parallelism] altera esse limite). Ele compartilha suas threads com [Dispatchers.Default], o que evita uma troca de thread ao passar de um para o outro.
[Dispatchers.Main]
a thread da interface gráfica. Ele só existe se o módulo correspondente for adicionado ao projeto: [kotlinx-coroutines-android], [kotlinx-coroutines-swing], [kotlinx-coroutines-javafx].
[Dispatchers.Unconfined]
Nenhuma thread específica: a corrotina começa na thread do chamador e, após uma suspensão, continua na thread que a retomou. É usado principalmente em testes e em casos muito específicos.

Além desses dispatchers, há o de [runBlocking], que executa suas corrotinas na thread que o chamou, e aqueles criados a partir de um executor Java por meio da função de extensão [asCoroutineDispatcher()]. O programa [Async09.kt] exibe a thread que executa cada trecho de código:

// qual thread executa uma corrotina, e o resto de seu código após uma suspensão? os dispatchers
package async09

import kotlinx.coroutines.CoroutineName
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.asCoroutineDispatcher
import kotlinx.coroutines.delay
import kotlinx.coroutines.joinAll
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withContext
import java.util.concurrent.Executors

fun main() {
    // o modo debug acrescenta ao nome da thread o nome e o número da corrotina que ela executa
    System.setProperty("kotlinx.coroutines.debug", "on")
    display("start of the program, ${Runtime.getRuntime().availableProcessors()} processors")
    runBlocking(CoroutineName("main")) {
        // 1 - a corrotina de runBlocking é executada pela thread que chamou runBlocking
        display("1 - runBlocking, before delay")
        delay(100)
        display("1 - runBlocking, after delay")

        // 2 - Dispatchers.Default: um pool de threads dimensionado para cálculo
        launch(Dispatchers.Default + CoroutineName("computation")) {
            display("2 - Dispatchers.Default")
        }.join()

        // 3 - Dispatchers.IO: um pool de threads maior, para operações bloqueantes
        launch(Dispatchers.IO + CoroutineName("io")) {
            display("3 - Dispatchers.IO")
        }.join()

        // 4 - withContext muda o dispatcher durante um bloco, na mesma corrotina
        val result = withContext(Dispatchers.Default) {
            display("4 - in withContext(Dispatchers.Default)")
            42
        }
        display("4 - back on the runBlocking thread, result = $result")

        // 5 - Dispatchers.Unconfined: o resto é executado pela thread que retoma a corrotina
        launch(Dispatchers.Unconfined + CoroutineName("free")) {
            display("5 - Dispatchers.Unconfined, before delay")
            delay(100)
            display("5 - Dispatchers.Unconfined, after delay")
        }.join()

        // 6 - um executor Java transformado em dispatcher: aqui, uma thread virtual por tarefa
        Executors.newVirtualThreadPerTaskExecutor().asCoroutineDispatcher().use { virtuals ->
            launch(virtuals + CoroutineName("virtual")) {
                display("6 - virtual threads, before delay")
                delay(100)
                display("6 - virtual threads, after delay")
            }.join()
        }

        // 7 - em Dispatchers.Default, uma corrotina pode mudar de thread após cada suspensão
        val a = launch(Dispatchers.Default + CoroutineName("A")) { work("A") }
        val b = launch(Dispatchers.Default + CoroutineName("B")) { work("B") }
        joinAll(a, b)
        display("end of the program")
    }
}

suspend fun work(name: String) {
    for (i in 1..3) {
        display("7 -   $name$i")
        delay(100)
    }
}

// exibição prefixada pela thread que a executa (para uma thread virtual, sua descrição completa)
fun display(message: String) {
    val thread = Thread.currentThread()
    println("[${if (thread.isVirtual) thread.toString() else thread.name}] $message")
}

Resultados:

> gradlew -q run -Pmain=async09.Async09Kt
[main] start of the program, 2 processors
[main @main#1] 1 - runBlocking, before delay
[main @main#1] 1 - runBlocking, after delay
[DefaultDispatcher-worker-1 @computation#2] 2 - Dispatchers.Default
[DefaultDispatcher-worker-1 @io#3] 3 - Dispatchers.IO
[DefaultDispatcher-worker-1 @main#1] 4 - in withContext(Dispatchers.Default)
[main @main#1] 4 - back on the runBlocking thread, result = 42
[main @free#4] 5 - Dispatchers.Unconfined, before delay
[kotlinx.coroutines.DefaultExecutor @free#4] 5 - Dispatchers.Unconfined, after delay
[VirtualThread[#25, @virtual#5]/runnable@ForkJoinPool-1-worker-1] 6 - virtual threads, before delay
[VirtualThread[#28, @virtual#5]/runnable@ForkJoinPool-1-worker-1] 6 - virtual threads, after delay
[DefaultDispatcher-worker-1 @A#6] 7 -   A1
[DefaultDispatcher-worker-2 @B#7] 7 -   B1
[DefaultDispatcher-worker-1 @A#6] 7 -   A2
[DefaultDispatcher-worker-1 @B#7] 7 -   B2
[DefaultDispatcher-worker-1 @A#6] 7 -   A3
[DefaultDispatcher-worker-1 @B#7] 7 -   B3
[main @main#1] end of the program

Comentários:

  • Linha 16: a propriedade de sistema [kotlinx.coroutines.debug] ativa o modo de depuração do kotlinx.coroutines (ela deve ser definida antes do primeiro uso da biblioteca; também pode ser passada à JVM: [-Dkotlinx.coroutines.debug]). Nesse modo, o nome da thread que executa uma corrotina é complementado, durante a execução, pelo nome da corrotina (fornecido por um elemento [CoroutineName] em seu contexto, ou [coroutine] por padrão) e por seu número: [main @main#1];
  • linhas 18–22: a corrotina de [runBlocking], chamada [main], é executada pela thread [main], tanto antes quanto depois da espera: [runBlocking] transforma a thread que o chama em um laço de eventos que executa suas corrotinas (linhas 3 e 4 dos resultados);
  • linhas 24–26: uma corrotina iniciada em [Dispatchers.Default], cujo contexto — formado com [+] — consiste em um dispatcher e um nome; ela é executada por uma thread chamada [DefaultDispatcher-worker-N] (linha 5);
  • linhas 29–31: uma corrotina iniciada em [Dispatchers.IO]; ela é executada por uma thread com o mesmo nome (linha 6), já que os dois dispatchers compartilham suas threads;
  • linhas 34–39: [withContext(context) { … }] é uma função de suspensão que executa um bloco em um contexto diferente — neste caso, outro dispatcher — dentro da mesma corrotina (o número permanece [#1]), depois volta ao dispatcher original e retorna o resultado do bloco (linhas 7 e 8). É o método padrão para executar um cálculo em [Dispatchers.Default] ou um código bloqueante em [Dispatchers.IO] sem alterar a forma do código: [val text = withContext(Dispatchers.IO) { file.readText() }];
  • linhas 41–45: com [Dispatchers.Unconfined], a corrotina começa na thread [main] — a thread do chamador (linha 9) — e continua após [delay] na thread que a retomou: [kotlinx.coroutines.DefaultExecutor], a thread de timer do kotlinx.coroutines, que gerencia os timeouts (linha 10). Esse é o comportamento das continuações não assíncronas de [CompletableFuture] ([thenApply], [thenRun]), que são executadas pela thread que conclui a operação;
  • Linhas 48–54: [Executors.newVirtualThreadPerTaskExecutor().asCoroutineDispatcher()] cria um dispatcher que atribui cada segmento de execução da corrotina a um executor Java — neste caso, um executor de threads virtuais. O dispatcher resultante deve ser fechado quando não for mais necessário, daí o uso de [use]. As linhas 11 e 12 mostram que o início e o restante da corrotina foram executados por duas threads virtuais diferentes (nºs 25 e 28): cada retomada é uma nova tarefa atribuída ao executor, que cria, portanto, uma nova thread virtual. Um dispatcher assim é útil para executar código bloqueante a partir de corrotinas sem ficar limitado pelo teto de 64 threads de [Dispatchers.IO]: as threads virtuais são liberadas pela JVM enquanto esperam;
  • linhas 57–60: duas corrotinas que exibem uma mensagem e depois esperam, três vezes seguidas, em [Dispatchers.Default]. [joinAll] espera o término de várias corrotinas. As linhas 13 a 18 mostram que uma corrotina não permanece presa a uma única thread: a corrotina B começa em [worker-2] e continua em [worker-1]. Portanto, em uma corrotina, nunca se deve presumir que o código posterior a uma suspensão seja executado pela mesma thread que o código anterior. Uma consequência prática: uma variável [ThreadLocal] (Capítulo 8) não é confiável em uma corrotina; em vez disso, a informação é armazenada no contexto da corrotina, que a acompanha em toda parte;
  • linhas 72–75: para uma thread virtual — cujo nome é vazio por padrão — exibimos sua descrição completa, que inclui seu número, seu nome (aqui, o da corrotina, adicionado pelo modo de depuração) e sua thread hospedeira.

A escolha do dispatcher é, portanto, importante:

  • [Dispatchers.Default] para cálculos. Uma corrotina que realiza um cálculo demorado ocupa uma de suas threads, exatamente como faria uma tarefa em um pool de threads: as corrotinas não aceleram os cálculos; elas facilitam a concorrência de operações de espera (tratar muitas operações de espera simultaneamente), e não o paralelismo de cálculos (executar vários cálculos ao mesmo tempo em vários processadores, como visto no capítulo anterior);
  • [Dispatchers.IO], ou um dispatcher de threads virtuais, para código bloqueante, junto com [withContext];
  • [Dispatchers.Main] em uma aplicação gráfica: uma corrotina iniciada na thread da interface pode atualizar os componentes gráficos, esperar uma operação (executada em outro lugar com [withContext]) sem congelar a interface e depois atualizá-la com o resultado, sem exigir nenhum tratamento especial: ao final de [withContext], a corrotina volta automaticamente à thread da interface. É assim que funciona o C#, em que a continuação de um método [async] volta à thread da interface, e é algo que o Java não permite sem passar explicitamente um executor a cada continuação.

Por fim, é possível limitar o número de threads que um dispatcher aloca a um conjunto de corrotinas com [limitedParallelism(n)]: [val base = Dispatchers.IO.limitedParallelism(10)] retorna um dispatcher que nunca executa mais de 10 corrotinas ao mesmo tempo, usando as threads de [Dispatchers.IO]. Com [limitedParallelism(1)], obtemos um dispatcher que executa apenas uma corrotina por vez, o que permite manipular um estado compartilhado sem bloqueios. Esse recurso, estável desde a versão 1.9 do kotlinx.coroutines, será usado mais adiante neste capítulo, na seção sobre paralelismo limitado.

9.3.5. O programa principal

Um programa que usa corrotinas deve iniciar a primeira delas a partir do código comum da função [main] e esperar seu término: caso contrário, a função [main] terminaria imediatamente, e o programa junto com ela (as threads dos dispatchers são threads daemon, que não impedem a JVM de encerrar). Há duas maneiras de fazer isso:

  • [fun main() = runBlocking { … }], que usamos desde o início do capítulo: [runBlocking] bloqueia a thread [main] até o fim da corrotina e de todas as corrotinas que ela iniciou. É o único lugar em que uma espera bloqueante é normal; nunca se deve chamar [runBlocking] a partir de uma corrotina ou de uma função de suspensão, pois isso bloqueia sua thread. Quando a última expressão do bloco não é do tipo [Unit], escrevemos [runBlocking<Unit> { … }]; caso contrário, a função [main] teria um tipo de retorno diferente, e a JVM deixaria de reconhecê-la como o programa principal;
  • [suspend fun main()]: a função [main] pode ser, ela própria, uma função de suspensão; o compilador cuida de iniciá-la como corrotina. Isso equivale ao método [static async Task Main()] em C#.

O programa [Async10.kt] faz uma contagem regressiva usando uma função de suspensão [main]:

// uma função main suspensa: uma contagem regressiva e o código de saída do programa
package async10

import kotlinx.coroutines.delay
import kotlin.system.exitProcess

suspend fun main(args: Array<String>) {
    // o número de segundos é passado como argumento
    val nbSeconds = args.singleOrNull()?.toIntOrNull()
    if (nbSeconds == null || nbSeconds < 0) {
        println("syntax: gradlew -q run -Pmain=async10.Async10Kt --args=\"nbSeconds\"")
        // o código de saída do programa: 0 para sucesso, outro valor para um erro
        exitProcess(1)
    }
    println("countdown started on thread [${Thread.currentThread().name}]")
    countdown(nbSeconds)
    println("finished, on thread [${Thread.currentThread().name}]")
}

// um loop comum: cada delay suspende a função, sem bloquear uma thread
suspend fun countdown(nbSeconds: Int) {
    for (i in nbSeconds downTo 1) {
        println("$i s left")
        delay(1000)
    }
}

Resultados, primeiro com e depois sem argumento:

1
2
3
4
5
6
> gradlew -q run -Pmain=async10.Async10Kt --args="3"
countdown started on thread [main]
3 s left
2 s left
1 s left
finished, on thread [kotlinx.coroutines.DefaultExecutor]
> gradlew -q run -Pmain=async10.Async10Kt
syntax: gradlew -q run -Pmain=async10.Async10Kt --args="nbSeconds"

Comentários:

  • linha 7: uma função de suspensão [main] , que recebe argumentos de linha de comando passados via Gradle por meio da opção [--args];
  • Linha 9: [singleOrNull()] retorna o único argumento ou [null] se não houver exatamente um, e [toIntOrNull()] o converte em um inteiro ou retorna [null] se não for um inteiro;
  • linhas 10–13: se o argumento estiver ausente ou incorreto, o programa termina com [exitProcess(1)] (uma função de [kotlin.system], que chama [System.exit]). O inteiro passado é o código de saída do programa (0 para sucesso, qualquer outro valor para um erro), que pode ser verificado por um script: [echo %ERRORLEVEL%] no Windows, [echo $?] no Linux. Quando iniciado pelo Gradle, um programa que termina com um código diferente de 0 faz a tarefa [run] falhar, e o Gradle então exibe suas próprias mensagens de erro após as do programa (elas não são reproduzidas aqui). O tipo de [exitProcess] é [Nothing] (Capítulo 3): o compilador sabe que essa função nunca retorna e, portanto, considera que, após o [if], [nbSeconds] não é [null]; ele pode ser usado como um [Int] (conversão inteligente de tipo);
  • Linhas 20–24: a contagem regressiva. O programa Java devia implementá-la por meio de recursão, com cada etapa encadeando a seguinte com [thenCompose]; aqui, é um laço comum, com um [delay] em cada iteração;
  • Os resultados revelam uma peculiaridade de [suspend fun main]: sua corrotina não tem dispatcher. Ela começa na thread [main] e, depois das esperas, continua na thread que a retomou — a thread de timer do kotlinx.coroutines ([kotlinx.coroutines.DefaultExecutor]) — exatamente como com [Dispatchers.Unconfined]. Isso não tem consequências aqui, mas é um motivo para preferir [fun main() = runBlocking { … }], cujo comportamento é mais bem definido, ou para especificar um dispatcher com [withContext] no corpo da função.

9.4. Concorrência estruturada

O curso de Java encerrou seu capítulo com uma visão geral da concorrência estruturada ([StructuredTaskScope], ainda em fase de preview no Java 25). Em Kotlin, ela não é apenas um complemento: é o princípio sobre o qual toda a biblioteca kotlinx.coroutines se baseia, e é preciso compreendê-la antes de prosseguir.

A ideia é simples: uma corrotina só pode ser iniciada dentro de um escopo ([CoroutineScope]), e o escopo só termina quando as corrotinas que ele iniciou terminam. As funções [launch] e [async] são funções de extensão de [CoroutineScope]: elas não podem ser chamadas em qualquer lugar, mas apenas dentro de um escopo, como o bloco de um [runBlocking], de um [launch] ou de um [async], cujo receptor ([this]) é um escopo. Cada escopo tem um [Job]; cada corrotina iniciada no escopo tem seu próprio [Job], que se torna filho do [Job] do escopo. As corrotinas de um programa formam, assim, uma árvore, cujas relações de parentesco têm três consequências:

Image

  • um pai espera seus filhos: um *[Job] só termina quando seu próprio código e todos os seus filhos terminaram. É por isso que *[runBlocking] esperava as corrotinas iniciadas em seu bloco sem que fosse preciso escrever nenhum código para isso;
  • o cancelamento se propaga para baixo: cancelar um [Job] cancela todos os seus filhos e os filhos deles;
  • a falha se propaga para cima: se um filho falha (seu código lança uma exceção), seu pai é cancelado, o que por sua vez cancela todos os seus outros filhos, e a exceção é repassada ao pai, depois ao pai deste, até a raiz ou até um trecho de código que a trate.

Como resultado, nenhuma corrotina pode ser “esquecida”: ela vive dentro de um escopo, que não pode terminar sem ela; se ela falha, alguém saberá; se a operação de que ela faz parte é abandonada, ela é encerrada. É a mesma disciplina dos blocos de código da programação estruturada (um bloco não termina antes das instruções que contém), aplicada à concorrência, daí o seu nome.

O programa [Async11.kt] ilustra essas três regras:

// concorrência estruturada: Job, pai e filhos, coroutineScope
package async11

import kotlinx.coroutines.async
import kotlinx.coroutines.cancelAndJoin
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay
import kotlinx.coroutines.job
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

var start = System.nanoTime()

fun main() = runBlocking<Unit> {
    // 1 - as corrotinas lançadas por uma corrotina são suas filhas: o pai espera o fim delas
    val parent = launch {
        launch {
            delay(300)
            display("  child 1 finished")
        }
        launch {
            delay(600)
            display("  child 2 finished")
        }
        val nbChildren = coroutineContext.job.children.count()
        display("  the parent launched $nbChildren children, its code is finished")
    }
    delay(100)
    display("1 - parent: isActive=${parent.isActive}, isCompleted=${parent.isCompleted}, " +
            "children=${parent.children.count()}")
    parent.join()
    display("1 - parent: isActive=${parent.isActive}, isCompleted=${parent.isCompleted}")

    // 2 - coroutineScope: a função lança corrotinas e só retorna após o fim delas
    start = System.nanoTime()
    val tray = prepareBreakfast()
    display("2 - breakfast served: $tray")

    // 3 - cancelar o pai cancela todos os seus filhos
    start = System.nanoTime()
    val parent3 = launch {
        for (number in 1..2) {
            launch {
                try {
                    delay(10_000)
                } finally {
                    display("  child $number: cancelled")
                }
            }
        }
    }
    delay(200)
    parent3.cancelAndJoin()
    display("3 - parent cancelled: isCancelled=${parent3.isCancelled}")

    // 4 - a falha de um filho cancela seus irmãos e sobe até o pai
    start = System.nanoTime()
    try {
        coroutineScope {
            launch {
                try {
                    delay(10_000)
                } finally {
                    display("  the sibling is cancelled")
                }
            }
            launch {
                delay(200)
                throw IllegalStateException("the toaster burned")
            }
        }
    } catch (e: IllegalStateException) {
        display("4 - coroutineScope threw: ${e.message}")
    }
}

// três preparações realizadas ao mesmo tempo; a função só retorna quando todas terminam
suspend fun prepareBreakfast(): String = coroutineScope {
    val coffee = async { prepare("coffee", 1000) }
    val toast = async { prepare("toast", 600) }
    // uma corrotina sem resultado: coroutineScope também esperará por ela
    launch { prepare("table set", 300) }
    "${coffee.await()} and ${toast.await()}"
}

// uma preparação que dura [ms] milissegundos
suspend fun prepare(what: String, ms: Long): String {
    display("  $what: start")
    delay(ms)
    display("  $what: ready")
    return what
}

// exibição com o tempo decorrido desde [start]
fun display(message: String) = println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

Resultados:

> gradlew -q run -Pmain=async11.Async11Kt
   48 ms :   the parent launched 2 children, its code is finished
  142 ms : 1 - parent: isActive=true, isCompleted=false, children=2
  361 ms :   child 1 finished
  661 ms :   child 2 finished
  664 ms : 1 - parent: isActive=false, isCompleted=true
    4 ms :   coffee: start
    4 ms :   toast: start
    4 ms :   table set: start
  304 ms :   table set: ready
  604 ms :   toast: ready
 1004 ms :   coffee: ready
 1011 ms : 2 - breakfast served: coffee and toast
  204 ms :   child 1: cancelled
  204 ms :   child 2: cancelled
  205 ms : 3 - parent cancelled: isCancelled=true
  201 ms :   the sibling is cancelled
  202 ms : 4 - coroutineScope threw: the toaster burned

Comentários:

  • linha 14: a última expressão do bloco é uma expressão [try] cujo tipo não é [Unit]; por isso, o tipo do resultado de [runBlocking] é especificado, como indicado no parágrafo anterior;
  • Linhas 15–26: uma corrotina [parent] inicia dois filhos, que duram 300 e 600 ms, e depois exibe o número de seus filhos: dentro do bloco de um [launch], [coroutineContext] é o contexto da corrotina, [coroutineContext.job] é o seu [Job], e a propriedade [children] deste último é a sequência de seus filhos. O código do pai termina imediatamente (linha 2 dos resultados);
  • linhas 28–30: 100 ms depois, o [Job] do pai ainda está ativo, assim como seus dois filhos (linha 3): um [Job] cujo código terminou está esperando seus filhos;
  • linhas 31–32: [join()] só devolve o controle 600 ms depois, quando o segundo filho terminou (linhas 4–6);
  • linhas 77–83: a função de suspensão [prepareBreakfast] trata três preparos simultaneamente. Para iniciar corrotinas, uma função de suspensão precisa de um escopo: [coroutineScope { … }] cria um novo escopo, cujo [Job] é filho da corrotina chamadora, executa o bloco, espera o término de todas as corrotinas iniciadas dentro do bloco e então retorna o valor do bloco. A função [prepareBreakfast] parece, portanto, vista de fora, uma função sequencial comum: quando ela devolve o controle, tudo o que ela iniciou está concluído, inclusive a corrotina da linha 82, que ninguém espera explicitamente terminar;
  • linhas 34–37: a chamada da função; o café da manhã é servido após um segundo, a duração do preparo mais longo (linhas 7–13);
  • linhas 39–54: um pai inicia dois filhos que esperam dez segundos. Após 200 ms, [cancelAndJoin()] aborta o pai e espera a conclusão do aborto: os dois filhos são abortados junto com ele (linhas 14–16). O bloco [finally] de cada filho é executado, exatamente como quando se sai de um bloco por meio de uma exceção: veremos na seção sobre cancelamento que é exatamente isso que acontece;
  • linhas 56–73: dentro de um escopo criado por [coroutineScope], um filho espera dez segundos e seu irmão falha após 200 ms. A falha cancela o escopo, que por sua vez cancela o primeiro filho (linha 17), e [coroutineScope] lança a exceção do filho que falhou (linha 18), que é capturada por um [try / catch] comum que envolve a chamada.

Duas funções criam, portanto, um escopo, com dois usos diferentes:

  • [runBlocking] cria o escopo raiz de um programa a partir de código comum, bloqueando a thread;
  • [coroutineScope] cria um escopo dentro de uma função de suspensão, sem bloquear nenhuma thread. É a maneira padrão de escrever uma função de suspensão que realiza várias operações de forma concorrente: vista de fora, a concorrência não é visível.

Daí decorre uma regra de estilo: uma função de suspensão deve ter concluído todo o seu trabalho quando devolve o controle. Uma função que inicia corrotinas destinadas a sobreviver a ela não deve ser uma função de suspensão, e sim uma função de extensão de [CoroutineScope] (como o próprio [launch] ): [fun CoroutineScope.monitor(): Job]. Sua assinatura indica, assim, que ela inicia corrotinas no escopo do chamador. Mais adiante neste capítulo, veremos que a biblioteca também oferece escopos cujos filhos são independentes uns dos outros ([supervisorScope]) e como criar um escopo específico para um componente da aplicação. O final do capítulo comparará a concorrência estruturada do Kotlin com a do Java.

9.5. Execução sequencial e execução concorrente

9.5.1. async e awaitAll

Como mostrou o exemplo do café, uma chamada a uma função de suspensão é sequencial, e, para realizar várias operações simultaneamente, é preciso iniciá-las explicitamente em corrotinas. O momento em que uma operação é iniciada ([val d = async { operation() }]) e o momento em que ela é aguardada ([d.await()]) podem, assim, ser separados, permitindo que outras operações sejam iniciadas nesse intervalo. O programa [Async12.kt] compara as duas abordagens usando operações que levam um segundo:

// execução sequencial e execução concorrente de operações de um segundo
package async12

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.async
import kotlinx.coroutines.asCoroutineDispatcher
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking
import java.util.concurrent.Executors
import kotlin.time.measureTimedValue

fun main() = runBlocking {
    // 1 - em sequência: cada operação termina antes que a próxima comece
    val (sequence, duration1) = measureTimedValue {
        val a = readTemperature("Angers")
        val b = readTemperature("Brest")
        val c = readTemperature("Colmar")
        listOf(a, b, c)
    }
    println("1 - in sequence: $sequence in ${duration1.inWholeMilliseconds} ms")

    // 2 - concorrentemente: as três operações são lançadas e depois aguardadas
    val (concurrent, duration2) = measureTimedValue {
        val a = async { readTemperature("Angers") }
        val b = async { readTemperature("Brest") }
        val c = async { readTemperature("Colmar") }
        listOf(a.await(), b.await(), c.await())
    }
    println("2 - concurrently: $concurrent in ${duration2.inWholeMilliseconds} ms")

    // 3 - uma lista de operações: map { async { … } } e depois awaitAll()
    val cities = listOf("Angers", "Brest", "Colmar", "Dijon", "Évry", "Foix")
    val (temperatures, duration3) = measureTimedValue {
        cities.map { city -> async { readTemperature(city) } }.awaitAll()
    }
    println("3 - ${cities.size} cities: $temperatures in ${duration3.inWholeMilliseconds} ms")

    // 4 - uma função bloqueante é entregue ao dispatcher IO
    val (temperatures4, duration4) = measureTimedValue {
        cities.map { city -> async(Dispatchers.IO) { readTemperatureBlocking(city) } }.awaitAll()
    }
    println("4 - ${cities.size} cities (Dispatchers.IO): $temperatures4 in ${duration4.inWholeMilliseconds} ms")

    // 5 - 100 operações bloqueantes no dispatcher IO, limitado a 64 threads
    val (hundredIO, duration5) = measureTimedValue {
        (1..100).map { async(Dispatchers.IO) { readTemperatureBlocking("city$it") } }.awaitAll()
    }
    println("5 - ${hundredIO.size} cities (Dispatchers.IO) in ${duration5.inWholeMilliseconds} ms")

    // 6 - o mesmo em um dispatcher de threads virtuais
    Executors.newVirtualThreadPerTaskExecutor().asCoroutineDispatcher().use { virtuals ->
        val (hundredVirtual, duration6) = measureTimedValue {
            (1..100).map { async(virtuals) { readTemperatureBlocking("city$it") } }.awaitAll()
        }
        println("6 - ${hundredVirtual.size} cities (virtual threads) in ${duration6.inWholeMilliseconds} ms")
    }
}

// simula a consulta a um serviço remoto que responde em um segundo
suspend fun readTemperature(city: String): Int {
    delay(1000)
    // uma "temperatura" derivada do nome da cidade
    return 10 + city.length
}

// a mesma operação, escrita de forma bloqueante
fun readTemperatureBlocking(city: String): Int {
    Thread.sleep(1000)
    return 10 + city.length
}

Resultados:

1
2
3
4
5
6
7
> gradlew -q run -Pmain=async12.Async12Kt
1 - in sequence: [16, 15, 16] in 3045 ms
2 - concurrently: [16, 15, 16] in 1027 ms
3 - 6 cities: [16, 15, 16, 15, 14, 14] in 1004 ms
4 - 6 cities (Dispatchers.IO): [16, 15, 16, 15, 14, 14] in 1061 ms
5 - 100 cities (Dispatchers.IO) in 2018 ms
6 - 100 cities (virtual threads) in 1026 ms

Comentários:

  • linhas 60–64: a operação simulada: uma espera de um segundo, seguida de uma “temperatura” derivada do comprimento do nome da cidade;
  • Linhas 14–21: cada operação é chamada diretamente e, portanto, termina antes que a próxima comece: 3 segundos (linha 2 dos resultados). A função [measureTimedValue { … }] da biblioteca padrão ([kotlin.time]) executa o bloco e retorna um objeto [TimedValue], que contém o valor do bloco e a duração de sua execução; trata-se de uma data class, que é decomposta em duas variáveis ([val (sequence, duration1) = …], Capítulo 3). A duração é um [Duration], em que [inWholeMilliseconds] representa o número de milissegundos. Como o bloco é a [inline], funções de suspensão podem ser chamadas dentro dele;
  • linhas 23–28: as três operações são iniciadas em três corrotinas com [async] e depois aguardadas. Elas são executadas simultaneamente: um segundo em vez de três (linha 3). A ordem das chamadas a [await] é irrelevante: a primeira espera a primeira operação terminar, enquanto as outras encontram as suas já concluídas ou quase;
  • Linhas 32–35: o caso de uma lista de operações. [cities.map { city -> async { … } }] inicia uma corrotina por cidade e produz uma lista de [Deferred<Int>]; a função de extensão [awaitAll()] para uma coleção de [Deferred] espera por todos eles e retorna a lista de seus resultados, na ordem das operações (e não na ordem em que terminaram). As seis operações juntas levam um segundo (linha 4). Comparado à versão Java ([allOf] sobre um array de [CompletableFuture], seguido de uma continuação que coleta os resultados com [join]), o código é direto;
  • linhas 39–43: o mesmo com uma função bloqueante ([readTemperatureBlocking], linhas 67–69), executada em [Dispatchers.IO]: cada operação bloqueia uma thread desse dispatcher; as seis juntas levam um segundo (linha 5);
  • linhas 45–49: com 100 operações bloqueantes, o limite de 64 threads de [Dispatchers.IO] torna-se evidente: 64 operações, depois as 36 restantes, totalizando dois segundos (linha 6). É a mesma starvation de threads já encontrada com o pool de 10 threads de [Async01.kt], mas em escala maior;
  • Linhas 51–56: as mesmas 100 operações bloqueantes em um dispatcher de threads virtuais: um segundo (linha 7), pois threads virtuais bloqueadas não retêm nenhuma thread do sistema. O parâmetro [virtuals] de [use] é o dispatcher, passado a [async] como contexto.

Essas duas últimas etapas demonstram como corrotinas e threads virtuais se complementam: corrotinas para o código escrito com funções de suspensão e threads virtuais — por meio de um dispatcher — para executar, a partir de corrotinas, uma grande quantidade de código bloqueante herdado do Java.

9.5.2. A primeira operação concluída: select

A função [select] (pacote [kotlinx.coroutines.selects]) suspende a corrotina até que ocorra um entre vários eventos e retorna o valor associado a esse evento. Cada evento possível é uma cláusula: [onAwait] para o término de um [Deferred] (a cláusula recebe seu resultado), [onJoin] para o término de um [Job], [onReceive] para a chegada de um valor em um canal… É o equivalente de [CompletableFuture.anyOf], com um resultado tipado. O programa [Async13.kt] o utiliza de três maneiras:

// select: reagir à primeira operação concluída
package async13

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.async
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.delay
import kotlinx.coroutines.joinAll
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.selects.select

var start = System.nanoTime()

fun main() = runBlocking {
    start = System.nanoTime()
    // 1 - três servidores espelho são consultados e a primeira resposta é mantida
    val requests = listOf(
        async { query("mirror-paris", 800) },
        async { query("mirror-lyon", 300) },
        async { query("mirror-lille", 600) })
    // select suspende a corrotina até que uma das cláusulas seja escolhida
    val first = select {
        requests.forEach { request -> request.onAwait { answer -> answer } }
    }
    display("1 - first answer: $first")
    // as outras requisições continuam: são aguardadas aqui para ver suas respostas
    display("1 - all the answers: ${requests.awaitAll()}")

    // 2 - a mesma coisa, mas as requisições que se tornaram inúteis são canceladas
    start = System.nanoTime()
    val requests2 = listOf(
        async { query("mirror-paris", 800) },
        async { query("mirror-lyon", 300) },
        async { query("mirror-lille", 600) })
    val first2 = select {
        requests2.forEach { request -> request.onAwait { answer -> answer } }
    }
    requests2.forEach { it.cancel() }
    // esperamos o fim das requisições canceladas
    requests2.joinAll()
    display("2 - first answer: $first2, the other requests are cancelled")

    // 3 - uma operação com tempo limitado: ela "corre" contra um delay
    start = System.nanoTime()
    val slow = async { query("slow-server", 2000) }
    val timer = launch { delay(500) }
    val answer: String? = select {
        slow.onAwait { it }
        timer.onJoin { null }
    }
    if (answer != null) {
        display("3 - answer obtained in time: $answer")
    } else {
        display("3 - the slow server did not answer within 500 ms: it is cancelled")
        slow.cancel()
    }
    slow.join()
    display("3 - end of the program")
}

// simula um servidor que responde após [duration] milissegundos
suspend fun query(server: String, duration: Long): String {
    try {
        delay(duration)
        return "$server ($duration ms)"
    } catch (e: CancellationException) {
        // a corrotina foi cancelada durante sua espera: isso é sinalizado e depois a exceção é relançada
        display("  $server: request cancelled (${e.javaClass.simpleName})")
        throw e
    }
}

// exibição com o tempo decorrido desde [start]
fun display(message: String) = println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

Resultados:

1
2
3
4
5
6
7
8
9
> gradlew -q run -Pmain=async13.Async13Kt
  374 ms : 1 - first answer: mirror-lyon (300 ms)
  854 ms : 1 - all the answers: [mirror-paris (800 ms), mirror-lyon (300 ms), mirror-lille (600 ms)]
  325 ms :   mirror-paris: request cancelled (JobCancellationException)
  329 ms :   mirror-lille: request cancelled (JobCancellationException)
  340 ms : 2 - first answer: mirror-lyon (300 ms), the other requests are cancelled
  524 ms : 3 - the slow server did not answer within 500 ms: it is cancelled
  524 ms :   slow-server: request cancelled (JobCancellationException)
  525 ms : 3 - end of the program

Comentários:

  • Linhas 62–70: o servidor simulado responde após o tempo especificado. Se a corrotina que o consulta for cancelada durante a espera, [delay] lança uma [CancellationException]: nós a capturamos para sinalizar o problema e depois a relançamos (veremos na seção sobre cancelamento por que isso é essencial). [kotlinx.coroutines.CancellationException] é um alias da classe [java.util.concurrent.CancellationException] do JDK; a exceção efetivamente lançada é de uma classe interna da biblioteca derivada dela, [JobCancellationException];
  • linhas 17–21: três servidores espelho são consultados; todos contêm as mesmas informações e respondem com velocidades variadas, cada um em uma corrotina;
  • Linhas 23–26: o bloco [select] declara uma cláusula [onAwait] para cada consulta; a lambda de cada cláusula recebe o resultado da consulta e retorna o valor de [select]. As cláusulas podem ser declaradas dentro de um laço, como mostrado aqui. O primeiro [Deferred] a terminar prevalece: a primeira resposta chega após pouco mais de 300 ms (linha 2 dos resultados; o primeiro uso de [select] carrega mais algumas classes); seu tipo é [String], sem conversão de tipo, ao contrário de [anyOf], que retorna um [Object];
  • linha 28: [select] não interrompeu as outras consultas, que continuam: [awaitAll()] espera que elas exibam todas as respostas (linha 3);
  • Linhas 30–42: na maioria dos casos, as outras requisições tornaram-se desnecessárias. Ao contrário de um [CompletableFuture], uma corrotina pode ser realmente encerrada: [cancel()] cancela cada requisição (cancelar uma requisição que já foi concluída não tem efeito), e [joinAll()] espera o término das requisições canceladas. As linhas 4 e 5 dos resultados mostram que as duas requisições pendentes foram interrompidas durante a espera; elas não consomem mais nenhum recurso;
  • linhas 44–59: um caso de uso clássico: uma corrida contra um limite de tempo. A cláusula [onJoin] do [Job] [timer], que espera 500 ms, retorna [null]; se ela vencer, a operação demorou demais e é cancelada (linhas 7–9). O tipo de [answer] é [String?]: [select] retorna a string da resposta ou [null]. O kotlinx.coroutines oferece uma maneira mais direta de tratar esse caso: a função [withTimeoutOrNull], descrita mais adiante.

9.5.3. Processando os resultados à medida que chegam

Muitas vezes queremos processar os resultados de várias operações à medida que elas terminam, sem esperar a mais lenta. O curso de Java fazia isso de duas maneiras: anexando uma continuação a cada [CompletableFuture] ou delegando as tarefas a um [ExecutorCompletionService], que entrega os [Future] na ordem em que as tarefas terminam. Com corrotinas, também há duas maneiras: usar o resultado dentro da própria corrotina que o produziu ou passar os resultados por um canal ([Channel]), uma fila entre corrotinas. O programa [Async14.kt] processa cinco “arquivos”, cada um dos quais leva entre 100 e 900 ms para ser processado, usando os dois métodos:

// processamento dos resultados na ordem em que as operações terminam
package async14

import kotlinx.coroutines.channels.Channel
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

var start = 0L
val durations = listOf(900L, 300L, 700L, 100L, 500L)

fun main() = runBlocking {
    // 1 - uma corrotina por arquivo: cada uma usa seu resultado assim que o tem
    start = System.nanoTime()
    coroutineScope {
        durations.forEachIndexed { i, duration ->
            launch { display(process("file$i.txt", duration)) }
        }
    } // coroutineScope espera o fim das cinco corrotinas
    display("1 - all the files have been processed")

    // 2 - as corrotinas enviam seus resultados a um canal, uma única corrotina os utiliza
    start = System.nanoTime()
    val results = Channel<String>()
    durations.forEachIndexed { i, duration ->
        launch { results.send(process("file$i.txt", duration)) }
    }
    // receive() suspende a corrotina até a chegada do próximo resultado
    repeat(durations.size) {
        display(results.receive())
    }
    display("2 - all the files have been processed")
}

// simula o processamento de um arquivo que dura [duration] milissegundos
suspend fun process(file: String, duration: Long): String {
    delay(duration)
    return "$file processed in $duration ms"
}

// exibição com o tempo decorrido desde [start]
fun display(message: String) = println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

Resultados:

> gradlew -q run -Pmain=async14.Async14Kt
  133 ms : file3.txt processed in 100 ms
  326 ms : file1.txt processed in 300 ms
  525 ms : file4.txt processed in 500 ms
  725 ms : file2.txt processed in 700 ms
  922 ms : file0.txt processed in 900 ms
  923 ms : 1 - all the files have been processed
  176 ms : file3.txt processed in 100 ms
  373 ms : file1.txt processed in 300 ms
  573 ms : file4.txt processed in 500 ms
  775 ms : file2.txt processed in 700 ms
  976 ms : file0.txt processed in 900 ms
  976 ms : 2 - all the files have been processed

Comentários:

  • linhas 36–39: o processamento simulado de um arquivo, que leva o tempo especificado;
  • linhas 14–21: cada processamento é iniciado em sua própria corrotina, que exibe seu resultado assim que ele fica disponível: o arquivo 3 (100 ms) é exibido primeiro, o arquivo 0 (900 ms) por último (linhas 2–6 dos resultados). Isso equivale à continuação anexada a cada [CompletableFuture], mas o processamento e a exibição são escritos um após o outro: [display(process(...))]. O bloco [coroutineScope] espera o término das cinco corrotinas; ele substitui o [allOf] do programa Java. A função [forEachIndexed] percorre a lista [durations], devolvendo ao mesmo tempo o índice e o elemento;
  • Linhas 23–33: as cinco corrotinas enviam seus resultados a um canal ([Channel<String>]) por meio da função de suspensão [send]; a corrotina principal os recebe um por um por meio da função de suspensão [receive()], que espera o próximo resultado disponível. Ela os recebe, portanto, na ordem em que os processamentos terminam (linhas 8–12): isso equivale ao [CompletionService] do Java, sem bloquear nenhuma thread. Um canal criado por [Channel<String>()] não tem buffer: cada [send] espera que uma corrotina receba o valor (é um “rendezvous”). Os canais serão discutidos em detalhes mais adiante neste capítulo;
  • nos dois casos, o processo inteiro dura 900 ms — a duração da operação mais longa — e cada resultado é processado o mais cedo possível. A primeira abordagem é adequada quando cada resultado pode ser processado independentemente dos outros; a segunda é adequada quando um único trecho de código deve recebê-los todos, por exemplo, para agregá-los ou exibi-los em uma interface gráfica.

9.6. Exceções em corrotinas

9.6.1. try/catch e propagação na concorrência estruturada

Com [CompletableFuture], uma exceção não é lançada de volta ao código que iniciou a operação: ela é armazenada no [CompletableFuture], propaga-se ao longo da cadeia de continuações e é tratada por meio de métodos dedicados ([exceptionally], [handle], [whenComplete]). Com funções de suspensão, a questão é muito mais simples: uma função de suspensão lança exceções exatamente como uma função comum, e elas são capturadas com [try / catch], mesmo que a exceção tenha sido lançada em outra thread após uma suspensão. Há apenas uma coisa nova a aprender: o que acontece quando uma corrotina iniciada por [launch] ou [async] falha. O programa [Async15.kt] examina os diferentes casos:

// exceções em corrotinas: try / catch comum, propagação na concorrência estruturada
package async15

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.Deferred
import kotlinx.coroutines.async
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.supervisorScope

fun main() = runBlocking<Unit> {
    // 1 - uma função suspensa lança suas exceções como uma função comum
    try {
        val value = readValue("twelve")
        println("value = $value")
    } catch (e: NumberFormatException) {
        println("1 - readValue throws ${name(e)} : ${e.message}")
    }

    // 2 - um valor de substituição em caso de falha: try é uma expressão
    val value = try {
        readValue("thirteen")
    } catch (_: NumberFormatException) {
        -1
    }
    println("2 - replacement value: $value")

    // 3 - catch trata a falha, finally é executado em todos os casos
    for (text in listOf("14", "fifteen")) {
        val report = try {
            "value ${readValue(text)}"
        } catch (e: NumberFormatException) {
            "failure, ${name(e)}"
        } finally {
            println("3 - finally: the reading of [$text] is finished")
        }
        println("3 - report: $report")
    }

    // 4 - um erro de parâmetro segue o mesmo caminho
    try {
        readValue(" ")
    } catch (e: IllegalArgumentException) {
        println("4 - readValue throws ${name(e)} : ${e.message}")
    }

    // 5 - várias operações em coroutineScope: a primeira falha cancela as outras
    val texts = listOf("1", "two", "3", "four")
    val readings = mutableListOf<Deferred<Int>>()
    try {
        coroutineScope {
            texts.forEach { text -> readings += async { readValue(text) } }
            println("5 - results: ${readings.awaitAll()}")
        }
    } catch (e: NumberFormatException) {
        println("5 - coroutineScope throws ${name(e)} : ${e.message}")
    }
    // cada operação guardou seu resultado ou sua exceção
    readings.forEachIndexed { i, reading -> println("      [${texts[i]}] : ${outcome(reading)}") }

    // 6 - capturar a exceção de await() não basta: a falha do filho já chegou ao pai
    try {
        coroutineScope {
            val reading = async { readValue("six") }
            val result = try {
                reading.await()
            } catch (e: NumberFormatException) {
                println("6 - await() threw ${name(e)}, caught")
                -1
            }
            println("6 - the code continues with $result…")
        }
    } catch (e: NumberFormatException) {
        println("6 - … but coroutineScope rethrows ${name(e)} : ${e.message}")
    }

    // 7 - supervisorScope: a falha de um filho só diz respeito a esse filho
    supervisorScope {
        val readings7 = texts.map { text -> async { readValue(text) } }
        readings7.forEachIndexed { i, reading -> println("7 - [${texts[i]}] : ${outcome(reading)}") }
    }
}

// uma operação que falha se a string não for um inteiro; ela dura 100 ms por caractere
suspend fun readValue(text: String): Int {
    // verificação do parâmetro
    require(text.isNotBlank()) { "the text must not be empty" }
    delay(100L * text.length)
    return text.toInt()
}

// o desfecho de uma operação: seu resultado, sua exceção ou seu cancelamento
suspend fun outcome(reading: Deferred<Int>): String = try {
    "success, result = ${reading.await()}"
} catch (e: CancellationException) {
    "cancelled (${name(e)})"
} catch (e: NumberFormatException) {
    "failure, ${name(e)} : ${e.message}"
}

// o nome simples da classe de uma exceção
fun name(e: Throwable): String = e.javaClass.simpleName

Resultados:

> gradlew -q run -Pmain=async15.Async15Kt
1 - readValue throws NumberFormatException : For input string: "twelve"
2 - replacement value: -1
3 - finally: the reading of [14] is finished
3 - report: value 14
3 - finally: the reading of [fifteen] is finished
3 - report: failure, NumberFormatException
4 - readValue throws IllegalArgumentException : the text must not be empty
5 - coroutineScope throws NumberFormatException : For input string: "two"
      [1] : success, result = 1
      [two] : failure, NumberFormatException : For input string: "two"
      [3] : success, result = 3
      [four] : cancelled (JobCancellationException)
6 - await() threw NumberFormatException, caught
6 - the code continues with -1…
6 - … but coroutineScope rethrows NumberFormatException : For input string: "six"
7 - [1] : success, result = 1
7 - [two] : failure, NumberFormatException : For input string: "two"
7 - [3] : success, result = 3
7 - [four] : failure, NumberFormatException : For input string: "four"

Comentários:

  • Linhas 86–91: a função testada. Ela primeiro verifica seu parâmetro com [require] (Capítulo 3), que lança uma [IllegalArgumentException] se a condição for falsa. Depois, espera 100 ms por caractere do texto e converte o texto inteiro, o que dispara uma [NumberFormatException] se ele não for um número;
  • linhas 14–19: o caso normal. A exceção lançada por [toInt()] após a suspensão é capturada tal como está pelo [try / catch] do chamador: nem [CompletionException], nem [ExecutionException], nem o método [cause] é usado para chegar à exceção original (linha 2 dos resultados);
  • linhas 22–28: [try] é uma expressão em Kotlin: seu valor é o do bloco [try] ou o do bloco [catch]. Isso equivale ao método [exceptionally] de [CompletableFuture] (linha 3). O parâmetro [_] indica que a exceção não é utilizada;
  • linhas 30–39: [catch] converte uma falha em um resultado (o equivalente de [handle]), [finally] é executado em todos os casos (equivalente a [whenComplete]): linhas 4 a 7. As ferramentas usuais são utilizadas;
  • linhas 42–46: em Java, um método que retorna um [CompletableFuture] podia falhar de duas maneiras — lançando uma exceção ao ser chamado (validação de parâmetros) ou retornando uma operação que falhou — e o chamador tinha de estar preparado para ambas. Uma função de suspensão tem apenas uma maneira de falhar: lançando uma exceção (linha 8);
  • linhas 49–58: quatro leituras são iniciadas com *[async] dentro de um escopo *[coroutineScope]* e são aguardadas com *[awaitAll()]*. A operação de leitura de ["two"] falha após 300 ms. De acordo com as regras da concorrência estruturada, a falha de um filho invalida seu pai, o escopo e, portanto, todos os seus outros filhos: a operação de leitura de ["four"], que deveria durar 400 ms, é invalidada. [coroutineScope] então lança a exceção do filho que falhou (linha 9). A linha 55 nunca é executada: [awaitAll()]* também lança a exceção;
  • linha 61: cada [Deferred] guardou seu resultado, que a função [outcome] (linhas 94–100) examina chamando [await()]: para uma operação concluída, [await()] retorna imediatamente seu resultado ou lança sua exceção e, para uma operação cancelada, lança uma [CancellationException]. As linhas 10 a 13 dos resultados mostram duas operações bem-sucedidas (["1"] e ["3"], que terminaram antes da falha), a falha e o cancelamento de ["four"]. Esse é o comportamento desejado na maioria dos casos: se qualquer uma das operações necessárias para um resultado falha, o resultado não pode ser produzido e não há por que continuar com as outras;
  • Linhas 63–76: uma armadilha clássica. A exceção lançada por [await()] é capturada e substituída por um valor padrão, e o código continua (linhas 14 e 15); mas a falha do filho já foi propagada ao seu pai, que foi cancelado: ao final de seu bloco, [coroutineScope] lança a exceção de qualquer maneira (linha 16). Para impedir que uma falha afete o pai, é preciso ou capturá-la na própria corrotina que falha ([async { try { readValue("six") } catch (e: NumberFormatException) { -1 } }]) ou usar um escopo de supervisão;
  • linhas 79–82: [supervisorScope { … }] cria um escopo de supervisão: como [coroutineScope], ele espera todos os seus filhos e os aborta se for abortado, mas a falha de um filho afeta somente ele mesmo: não aborta nem o escopo nem os outros filhos. Cada operação de leitura é executada até o fim, e o chamador examina o resultado de cada uma (linhas 17–20): desta vez, a operação de leitura de ["four"] falhou em vez de ser cancelada. É isso que se precisa quando as operações são independentes: exibir as temperaturas de seis cidades mesmo que uma delas não responda, por exemplo.

O curso de Java concluiu que as exceções em threads virtuais são tratadas como as do código comum, exceto na fronteira entre duas threads; isso também vale para as corrotinas, e a concorrência estruturada resolve o problema da fronteira: a falha de uma corrotina filha é automaticamente propagada de volta à corrotina pai.

9.6.2. As corrotinas esquecidas, CoroutineExceptionHandler, SupervisorJob e GlobalScope

O curso de Java mostrou que a exceção de uma operação que ninguém esperava era perdida, sem nenhuma mensagem. Na concorrência estruturada, uma corrotina não pode realmente ser esquecida: seu escopo a aguarda e, em um escopo comum, sua falha é propagada ao pai. Mas um escopo de supervisão não cancela o pai, e há maneiras de iniciar uma corrotina fora de qualquer estrutura: o que acontece com as exceções nesse caso? O programa [Async16.kt] demonstra isso:

// corrotinas cujo resultado ninguém aguarda: para onde vão suas exceções?
package async16

import kotlinx.coroutines.CoroutineExceptionHandler
import kotlinx.coroutines.CoroutineName
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.DelicateCoroutinesApi
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.GlobalScope
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.async
import kotlinx.coroutines.cancel
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.supervisorScope

// o handler das exceções que nenhuma corrotina capturou
val handler = CoroutineExceptionHandler { context, e ->
    println("CoroutineExceptionHandler: ${e.message} (coroutine ${context[CoroutineName]?.name})")
}

@OptIn(DelicateCoroutinesApi::class)
fun main() {
    // o handler das exceções não capturadas das threads
    Thread.setDefaultUncaughtExceptionHandler { thread, e ->
        println("uncaught exception in [${thread.name}] : ${e.message}")
    }
    runBlocking {
        supervisorScope {
            // 1 - um Deferred aguardado: sua exceção é capturada
            val a = async { save("a") }
            try {
                a.await()
            } catch (e: IllegalStateException) {
                println("1 - awaited Deferred: exception caught: ${e.message}")
            }

            // 2 - um Deferred que ninguém aguarda: sua exceção permanece no objeto
            async { save("b") }
            println("2 - forgotten Deferred: the coroutine is launched")

            // 3 - um Job não tem resultado onde guardar a exceção: ela vai para o handler da thread
            launch { save("c") }
            println("3 - launch without a handler: the coroutine is launched")

            // 4 - … ou para o CoroutineExceptionHandler presente no contexto da corrotina
            launch(handler + CoroutineName("saver-d")) { save("d") }
            println("4 - launch with a CoroutineExceptionHandler: the coroutine is launched")

            // 5 - lançar sem esperar, mas tratando a falha por conta própria
            launch {
                try {
                    save("e")
                } catch (e: IllegalStateException) {
                    println("5 - failure handled by the coroutine itself: ${e.message}")
                }
            }

            // o programa continua seu trabalho…
            for (i in 1..3) {
                delay(100)
                println("the program is working ($i)")
            }
        } // supervisorScope espera todos os seus filhos, mesmo os "esquecidos"

        // 6 - um escopo específico de um componente da aplicação, com um SupervisorJob
        val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default + handler)
        scope.launch(CoroutineName("saver-f")) { save("f") }
        scope.launch(CoroutineName("counter")) {
            repeat(3) {
                delay(100)
                println("6 - the counter continues its work despite the failure of its sibling ($it)")
            }
        }
        delay(400)
        // o fim do componente: tudo o que seu escopo lançou é cancelado
        scope.cancel()

        // 7 - GlobalScope: uma corrotina lançada fora de qualquer estrutura, que ninguém aguarda
        GlobalScope.launch { save("g") }
        GlobalScope.launch {
            delay(1000)
            println("7 - this message will never be displayed")
        }
        delay(300)
    }
    println("normal end of the program")
}

// uma operação que falha após 200 ms
suspend fun save(data: String) {
    delay(200)
    throw IllegalStateException("failure saving [$data]")
}

Resultados:

> gradlew -q run -Pmain=async16.Async16Kt
1 - awaited Deferred: exception caught: failure saving [a]
2 - forgotten Deferred: the coroutine is launched
3 - launch without a handler: the coroutine is launched
4 - launch with a CoroutineExceptionHandler: the coroutine is launched
the program is working (1)
uncaught exception in [main] : failure saving [c]
CoroutineExceptionHandler: failure saving [d] (coroutine saver-d)
5 - failure handled by the coroutine itself: failure saving [e]
the program is working (2)
the program is working (3)
6 - the counter continues its work despite the failure of its sibling (0)
CoroutineExceptionHandler: failure saving [f] (coroutine saver-f)
6 - the counter continues its work despite the failure of its sibling (1)
6 - the counter continues its work despite the failure of its sibling (2)
uncaught exception in [DefaultDispatcher-worker-1] : failure saving [g]
normal end of the program

Comentários:

  • linhas 91–94: a operação usada por todos os casos, que falha após 200 ms;
  • linhas 26–27: como no programa Java, configuramos o tratador chamado quando uma exceção não é capturada por nenhum código em uma thread. Sem ele, a JVM imprime o stack trace da exceção na saída de erro;
  • linhas 18–20: um *[CoroutineExceptionHandler] é um elemento de contexto que recebe as exceções que nenhuma corrotina tratou; ele é criado com uma lambda que recebe o contexto da corrotina que falhou e a exceção. [context[CoroutineName]] retorna o elemento [CoroutineName] do contexto, ou [null]* se não houver nenhum: o contexto é usado como um array associativo indexado pelo tipo dos elementos;
  • Todas as corrotinas dos casos 1 a 5 são iniciadas em um *[supervisorScope]*: a falha de uma delas não se propaga ao pai; portanto, outra parte deve tratá-la;
  • linhas 31–36: a operação é aguardada com [await()]; sua exceção é capturada normalmente (linha 2 dos resultados);
  • linhas 39–41: uma corrotina iniciada por [async], para a qual ninguém chama [await()]. Sua exceção é armazenada no [Deferred], que é ignorado: ela se perde, exatamente como a de um [CompletableFuture] esquecido, e nada a exibe. Uma corrotina iniciada por [async] foi concebida para ser aguardada; se seu resultado não for necessário, use [launch];
  • linhas 43–45: uma corrotina iniciada por [launch] não tem um resultado no qual armazenar sua exceção. Se seu pai não a trata (como ocorre dentro de um escopo de supervisão), a exceção é passada ao [CoroutineExceptionHandler] do contexto e, na falta dele, ao tratador de exceções não capturadas da thread que executava a corrotina, neste caso [main] (linha 7). No entanto, a thread não é interrompida: ela continua a executar as outras corrotinas;
  • linhas 47–49: a mesma corrotina, com um [CoroutineExceptionHandler] em seu contexto: é ele que recebe a exceção (linha 8);
  • linhas 51–56: a melhor maneira de iniciar uma operação sem esperar seu resultado: a corrotina trata sua própria falha, com um [try / catch] (linha 9);
  • linhas 60–65: o programa continua seu trabalho; ao final do bloco, [supervisorScope] espera todos os seus filhos, inclusive aqueles que pensávamos ter “esquecido”;
  • Linhas 67–78: um componente da aplicação (uma tela, um serviço, uma conexão) que inicia corrotinas destinadas a durar tanto quanto o próprio componente — e não apenas durante uma chamada de função — precisa de seu próprio escopo. Ele é criado com a função [CoroutineScope(context)], geralmente junto com um [SupervisorJob()], um *[Job]* em que a falha de um filho não encerra os outros (o equivalente de *[supervisorScope] para um escopo criado dessa maneira), um dispatcher e um tratador de exceções. As corrotinas iniciadas por [scope.launch { … }] são filhas do [SupervisorJob]: a falha de [saver-f], repassada ao tratador (linha 13), não impede que [counter] continue seu trabalho (linhas 12–15). Quando o componente desaparece, [scope.cancel()] cancela tudo o que o escopo iniciou: nenhuma corrotina sobrevive ao seu componente. É isso que fazem os escopos dos frameworks, como [viewModelScope] e [lifecycleScope]* no Android;
  • linhas 80–86: [GlobalScope] é um escopo global, sem [Job], que existe durante toda a vida do programa. Uma corrotina iniciada por [GlobalScope.launch] não tem pai: ninguém a espera, ninguém a cancela, e sua exceção é passada ao tratador da thread que a executava (neste caso, uma thread de [Dispatchers.Default], o dispatcher padrão de [GlobalScope]: linha 16). A segunda corrotina, que deveria exibir uma mensagem após um segundo, é simplesmente abandonada: [runBlocking] não a espera, e o programa termina sem ela (linha 17);
  • linha 23: [GlobalScope] é anotado com [@DelicateCoroutinesApi]: usá-lo provoca um aviso do compilador, que é um erro com a opção [allWarningsAsErrors] em nosso projeto:
warning: this is a delicate API and its use requires care. Make sure you fully read and understand documentation of the declaration that is marked as a delicate API.
  • A anotação [@OptIn(DelicateCoroutinesApi::class)] colocada na função informa ao compilador que sabemos o que estamos fazendo e faz o aviso desaparecer. Esse mecanismo de “opt-in” é usado pelas bibliotecas Kotlin para sinalizar APIs delicadas ou ainda experimentais.

A regra é a mesma do Java, mas a concorrência estruturada a torna quase automática: toda corrotina deve pertencer a um escopo que a espera, e sua falha deve ser tratada — seja pela própria corrotina, por seu pai ou por um [CoroutineExceptionHandler]. Evitamos [GlobalScope], exceto para raras corrotinas que realmente precisam viver tanto quanto o programa; em vez disso, criamos um escopo por componente, que destruímos ao fim de sua vida útil.

9.7. Cancelamento e timeouts

9.7.1. Cancelamento cooperativo

Uma operação demorada deve poder ser cancelada: o usuário clicou em [Cancel], um cliente de servidor se desconectou, uma janela da aplicação foi fechada ou um timeout foi excedido. O Java usa para isso a interrupção de threads: [interrupt()] define um flag; as esperas bloqueantes são interrompidas lançando [InterruptedException]; e um cálculo deve verificar o flag por conta própria. O curso de Java também apontou uma armadilha: o método [cancel] de um [CompletableFuture] não interrompe nada, pois um [CompletableFuture] não sabe qual thread trabalha para ele.

As corrotinas têm seu próprio mecanismo, que também é cooperativo, mas integrado à biblioteca:

  • o método [cancel()] de um [Job] (ou de um [Deferred]) o coloca no estado “cancelando”; ele não encerra a corrotina à força, nem faz o chamador esperar. [join()] espera então o término da corrotina; [cancelAndJoin()] faz as duas coisas;
  • se a corrotina está suspensa em uma das funções de suspensão do kotlinx.coroutines ([delay], [await], [join], [receive], [withContext]…), essa função retoma imediatamente a corrotina fazendo-a lançar uma [CancellationException]. O mesmo vale se a corrotina chamar uma dessas funções quando já estiver cancelada. Todas essas funções são ditas canceláveis;
  • A exceção sobe pela pilha de chamadas como uma exceção comum, executando no caminho os blocos [finally] e as funções [use], o que libera os recursos de forma limpa. Ao chegar ao topo da corrotina, ela a encerra no estado “cancelada”; isso não é uma falha: uma [CancellationException] nunca é passada ao pai nem aos tratadores de exceções;
  • uma corrotina que realiza cálculos sem nunca chamar uma função de suspensão não é afetada: ela deve verificar por conta própria seu estado com [isActive] (verdadeiro enquanto não for cancelada), [ensureActive()] (que lança uma [CancellationException] se ela foi cancelada) ou [yield()] (que cede a thread a outras corrotinas e verifica o cancelamento no processo);
  • cancelar um [Job] cancela seus filhos, como vimos na concorrência estruturada.

O programa [Async17.kt] cancela um download simulado e um cálculo simulado de várias maneiras:

// cancelamento de uma corrotina: cancel, cancelamento cooperativo, finally e NonCancellable
package async17

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.NonCancellable
import kotlinx.coroutines.cancelAndJoin
import kotlinx.coroutines.currentCoroutineContext
import kotlinx.coroutines.delay
import kotlinx.coroutines.isActive
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withContext
import kotlinx.coroutines.yield

var start = 0L

fun main() = runBlocking {
    // 1 - um download feito de esperas delay pode ser cancelado sem nada de especial
    start = System.nanoTime()
    val downloading = launch { download(10) }
    delay(1000)
    // cancel() solicita o cancelamento, join() espera até que a corrotina termine de parar
    downloading.cancel()
    downloading.join()
    display("1 - isCancelled=${downloading.isCancelled}, isCompleted=${downloading.isCompleted}")

    // 2 - um cálculo que nunca suspende ignora o pedido de cancelamento
    start = System.nanoTime()
    val computation2 = launch(Dispatchers.Default) { compute(checkCancellation = false) }
    delay(300)
    display("2 - cancellation request of the computation")
    computation2.cancelAndJoin()
    display("2 - isCancelled=${computation2.isCancelled}")

    // 3 - um cálculo que verifica regularmente se foi cancelado
    start = System.nanoTime()
    val computation3 = launch(Dispatchers.Default) { compute(checkCancellation = true) }
    delay(300)
    display("3 - cancellation request of the computation")
    computation3.cancelAndJoin()
    display("3 - isCancelled=${computation3.isCancelled}")

    // 4 - na thread de runBlocking, yield() deixa as outras corrotinas trabalharem
    start = System.nanoTime()
    val computation4 = launch {
        var rounds = 0L
        while (true) {
            rounds++
            // a cada dez milhões de iterações, a thread é cedida (e o cancelamento é verificado)
            if (rounds % 10_000_000 == 0L) yield()
        }
    }
    delay(300)
    display("4 - the main coroutine was able to take over again: cancellation of the computation")
    computation4.cancelAndJoin()
    display("4 - isCancelled=${computation4.isCancelled}")

    // 5 - a limpeza de uma corrotina cancelada: finally, e NonCancellable se ela precisar suspender
    start = System.nanoTime()
    val downloading5 = launch {
        try {
            download(10)
        } finally {
            // uma corrotina cancelada não pode mais suspender: delay lançaria imediatamente uma exceção…
            try {
                delay(100)
            } catch (e: CancellationException) {
                display("  finally: delay throws ${e.javaClass.simpleName}")
            }
            // … exceto em um bloco executado com o contexto NonCancellable
            withContext(NonCancellable) {
                display("  finally: closing the connection…")
                delay(200)
                display("  finally: connection closed")
            }
        }
    }
    delay(700)
    downloading5.cancelAndJoin()
    display("5 - end of the cancelled download")
}

// simula o download de [nbBlocks] blocos de dados (um bloco a cada 300 ms)
suspend fun download(nbBlocks: Int) {
    try {
        for (i in 1..nbBlocks) {
            // delay lança uma CancellationException se a corrotina for cancelada durante a espera
            delay(300)
            display("  block $i/$nbBlocks received")
        }
    } catch (e: CancellationException) {
        display("  download cancelled (${e.javaClass.simpleName})")
        // uma CancellationException capturada deve ser relançada
        throw e
    }
}

// um cálculo longo; se necessário, ele verifica a cada dez milhões de iterações se sua corrotina está ativa
suspend fun compute(checkCancellation: Boolean) {
    var sum = 0L
    for (i in 1..1_000_000_000L) {
        if (checkCancellation && i % 10_000_000 == 0L && !currentCoroutineContext().isActive) {
            display("  computation interrupted at round $i")
            return
        }
        sum += i % 7
    }
    display("  computation finished, sum = $sum")
}

// exibição com o tempo decorrido desde [start]
fun display(message: String) = println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

Resultados:

> gradlew -q run -Pmain=async17.Async17Kt
  322 ms :   block 1/10 received
  647 ms :   block 2/10 received
  947 ms :   block 3/10 received
 1022 ms :   download cancelled (JobCancellationException)
 1027 ms : 1 - isCancelled=true, isCompleted=true
  314 ms : 2 - cancellation request of the computation
 1237 ms :   computation finished, sum = 3000000003
 1240 ms : 2 - isCancelled=true
  301 ms : 3 - cancellation request of the computation
  306 ms :   computation interrupted at round 170000000
  307 ms : 3 - isCancelled=true
  323 ms : 4 - the main coroutine was able to take over again: cancellation of the computation
  324 ms : 4 - isCancelled=true
  301 ms :   block 1/10 received
  602 ms :   block 2/10 received
  700 ms :   download cancelled (JobCancellationException)
  705 ms :   finally: delay throws JobCancellationException
  707 ms :   finally: closing the connection…
  908 ms :   finally: connection closed
  909 ms : 5 - end of the cancelled download

Comentários:

  • Linhas 84–95: o download simulado recebe um bloco a cada 300 ms. Ele não requer nenhuma medida especial para ser cancelável: [delay] é cancelável. Capturamos [CancellationException] para sinalizar o cancelamento e depois a relançamos: uma [CancellationException] capturada deve sempre ser relançada; caso contrário, a corrotina continuaria como se nada tivesse acontecido, mesmo estando cancelada (e qualquer função cancelável que ela chamasse em seguida lançaria imediatamente uma nova exceção). Pelo mesmo motivo, desconfie de um ***[catch (e: Exception)]**, que também captura *[CancellationException]*, ou da função da biblioteca padrão [runCatching]*, que captura tudo;
  • linhas 19–26: após um segundo, o programa cancela o download com *[cancel()] e depois espera seu término com *[join()]. O download para imediatamente, no meio da espera pelo quarto bloco (linhas 2–5 dos resultados); uma corrotina cancelada e terminada tem [isCancelled=true] e [isCompleted=true] (linha 6). Ao contrário de [cancel] em um [CompletableFuture], a própria operação é interrompida, e não apenas a espera por seu resultado;
  • linhas 99–109: um bilhão de iterações de um cálculo arbitrário. Se solicitado, o cálculo verifica a cada dez milhões de iterações se sua corrotina ainda está ativa: [currentCoroutineContext()] retorna o contexto da corrotina atual, e sua propriedade de extensão [isActive] indica se o [Job] associado a esse contexto está ativo. Poderíamos ter escrito [currentCoroutineContext().ensureActive()] no lugar, o que lança uma [CancellationException] se a corrotina foi cancelada;
  • linhas 28–34: o cálculo é iniciado em [Dispatchers.Default] sem verificação. O pedido de cancelamento aos 300 ms (linha 7) não tem efeito sobre ele: ele é executado até o fim (linha 8), e [cancelAndJoin()] espera essa conclusão. [Job] está, no entanto, no estado cancelado (linha 9);
  • linhas 36–42: o mesmo cálculo, com a verificação: ele para alguns milissegundos após o pedido de cancelamento (linhas 10–12);
  • linhas 44–57: um cálculo infinito é iniciado, desta vez na thread de [runBlocking], que ele compartilha com a corrotina principal. Sem [yield()], ele ficaria com a thread só para si: a corrotina principal nunca conseguiria ser retomada após seu [delay(300)], nem, portanto, cancelar o cálculo, e o programa nunca terminaria. [yield()] suspende a corrotina e a recoloca na fila de seu dispatcher, o que deixa a thread disponível para outras corrotinas; se a corrotina tiver sido cancelada nesse meio-tempo, [yield()] lança uma [CancellationException], que interrompe o laço (linhas 13 e 14);
  • Linhas 59–81: limpeza de uma corrotina cancelada em um bloco [finally]. Fechar uma conexão pode exigir a chamada de uma função de suspensão; porém, uma corrotina cancelada não pode mais se suspender: qualquer função cancelável lança imediatamente uma [CancellationException], como mostra o [delay(100)] no bloco [finally] (linha 18). Para executar mesmo assim um código que suspende, ele é executado com [withContext(NonCancellable) { … }]: [NonCancellable] é um [Job] que nunca é cancelado, e o bloco é executado normalmente até terminar (linhas 19 e 20). O bloco deve ser curto: ele atrasa a conclusão do cancelamento, que [cancelAndJoin()] está esperando (linha 21).

Observe que o cancelamento não é uma interrupção abrupta: é uma exceção, lançada nos pontos de suspensão, que percorre o código de volta executando os blocos [finally]. Qualquer código escrito com funções de suspensão canceláveis pode ser cancelado sem esforço; um cálculo longo deve verificar regularmente [isActive] ou chamar [ensureActive()] ou [yield()].

9.7.2. Vários processos, vários resultados

O programa [Async18.kt] retoma o programa Java que iniciava cinco processos com duração de 1 a 5 segundos, dos quais o processo nº 3 lança uma exceção e o processo nº 4 é cancelado. Ele trata cada processo assim que termina, independentemente de como terminou, e sempre sabe de qual processo se trata:

// cinco processamentos de 1 a 5 segundos: o nº 3 lança uma exceção, o nº 4 é cancelado
package async18

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.async
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.selects.select
import kotlinx.coroutines.supervisorScope

// o resultado de um processamento
data class ProcessingResult(val duration: Int, val actualDuration: Double)

var start = 0L

fun main() = runBlocking {
    start = System.nanoTime()
    // supervisorScope: a falha de um processamento não cancela os outros
    supervisorScope {
        val processings = List(5) { number -> async { sleep(number, number + 1) } }
        // o processamento nº 4 é cancelado após 2,5 segundos
        launch {
            delay(2500)
            processings[4].cancel()
        }
        display("the ${processings.size} processings are launched")

        // cada processamento é usado assim que termina, qualquer que seja a forma como termina
        val inProgress = processings.withIndex().toMutableList()
        while (inProgress.isNotEmpty()) {
            // select devolve o primeiro processamento terminado, com seu número
            val finished = select {
                inProgress.forEach { processing -> processing.value.onJoin { processing } }
            }
            inProgress.remove(finished)
            val (number, processing) = finished
            // o processamento terminou: await() devolve imediatamente seu resultado ou lança sua exceção
            val report = try {
                val result = processing.await()
                "finished: scheduled duration %d s, actual duration %.1f s"
                    .format(result.duration, result.actualDuration)
            } catch (_: CancellationException) {
                "cancelled"
            } catch (e: IllegalStateException) {
                "encountered the following error: ${e.message}"
            }
            display("processing $number $report")
        }
    }
}

// o processamento: dormir por [duration] segundos, em fatias de um segundo
suspend fun sleep(number: Int, duration: Int): ProcessingResult {
    val processingStart = System.nanoTime()
    // exceção do processamento nº 3
    check(number != 3) { "test...." }
    repeat(duration) { delay(1000) }
    // o resultado devolvido ao chamador
    return ProcessingResult(duration, (System.nanoTime() - processingStart) / 1e9)
}

// exibição com o tempo decorrido desde o início, em segundos
fun display(message: String) = println("%4.1f s : %s".format((System.nanoTime() - start) / 1e9, message))

Resultados:

1
2
3
4
5
6
7
> gradlew -q run -Pmain=async18.Async18Kt
 0.0 s : the 5 processings are launched
 0.1 s : processing 3 encountered the following error: test....
 1.1 s : processing 0 finished: scheduled duration 1 s, actual duration 1.0 s
 2.1 s : processing 1 finished: scheduled duration 2 s, actual duration 2.0 s
 2.6 s : processing 4 cancelled
 3.1 s : processing 2 finished: scheduled duration 3 s, actual duration 3.0 s

Comentários:

  • Linhas 53–60: o processamento. O processo nº 3 falha imediatamente: a função [check] (Capítulo 3) lança uma [IllegalStateException] se sua condição for falsa. Os outros “dormem” por [duration] segundos, em incrementos de um segundo, com [delay] (que pode ser cancelado), e retornam um resultado — uma data class ([ProcessingResult], linha 13) — que contém a duração prevista e a duração real;
  • linha 20: os processos são independentes: dentro de um escopo de supervisão, a falha do processo nº 3 não cancela os outros;
  • linha 21: os cinco processos são iniciados com [async]; a lista dos cinco [Deferred<ProcessingResult>] é construída por [List(5) { number -> … }];
  • linhas 22–25: uma corrotina cancelará o processo nº 4 após 2,5 segundos, mesmo que ainda lhe restem 2,5 segundos de sono. O programa Java precisava de um *[ScheduledExecutorService]* para isso; aqui, basta uma corrotina que começa com um *[delay]* ;
  • linha 30: [withIndex()] associa cada tarefa ao seu número, na forma de objetos [IndexedValue] (uma data class com duas propriedades, [index] e [value]), armazenados em uma lista mutável de processos em andamento;
  • linhas 33–36: enquanto houver processos em andamento, [select] espera o primeiro terminar, independentemente de como ele termine: a cláusula [onJoin] de um [Job] é selecionada assim que ele é concluído — com sucesso, sem sucesso ou cancelado. A cláusula retorna o [IndexedValue] do processo, que é então removido da lista;
  • linha 37: a atribuição por desestruturação separa o número do processo;
  • linhas 39–46: o resultado do processamento é examinado com [await()], que não bloqueia mais a execução: ele retorna o resultado, lança a exceção do processamento ou lança uma [CancellationException] se ele foi cancelado. A ordem dos [catch] é importante: [CancellationException] deriva de [IllegalStateException] (é uma subclasse do JDK), portanto deve ser capturada primeiro. Capturar uma *[CancellationException]* sem relançá-la é válido aqui porque ela vem de outro *[Job]* — o processo cancelado — e não da corrotina que a captura;
  • os resultados mostram que o nº 3 falha imediatamente, que os nºs 0, 1 e 2 terminam após 1, 2 e 3 segundos, respectivamente, e que o nº 4 é cancelado aos 2,5 segundos. O programa Java verificava o estado do [Future] usando [switch] para examinar as constantes de [Future.State]; com corrotinas, o resultado de um processo é lido naturalmente com [try / catch].

9.7.3. Limitando a duração de uma espera: withTimeout e withTimeoutOrNull

O kotlinx.coroutines fornece duas funções de suspensão que limitam a duração de um bloco de código:

  • [withTimeout(timeout) { … }] executa o bloco e retorna seu valor; se o bloco não for concluído dentro do limite de tempo, ele é cancelado, e [withTimeout] lança uma [TimeoutCancellationException] (uma classe derivada de [CancellationException]);
  • [withTimeoutOrNull(timeout) { … }] faz o mesmo, mas retorna [null] em vez de lançar uma exceção.

O timeout é expresso em milissegundos ou como uma duração ([withTimeout(2.seconds)]). O programa [Async19.kt] demonstra essas duas funções, seus limites (o código bloqueante) e como combinar duas condições de término:

// limitando a duração de uma espera: withTimeout, withTimeoutOrNull, runInterruptible
package async19

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.TimeoutCancellationException
import kotlinx.coroutines.cancelAndJoin
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.runInterruptible
import kotlinx.coroutines.withContext
import kotlinx.coroutines.withTimeout
import kotlinx.coroutines.withTimeoutOrNull

var start = 0L

fun main() = runBlocking {
    // 1 - withTimeout: não esperamos mais que um segundo, e a operação é cancelada
    start = System.nanoTime()
    try {
        display("1 - answer: ${withTimeout(1000) { query("slow-server", 3000) }}")
    } catch (e: TimeoutCancellationException) {
        display("1 - ${e.javaClass.simpleName} : ${e.message}")
    }

    // 2 - withTimeoutOrNull: além de um segundo, nos contentamos com uma resposta padrão
    start = System.nanoTime()
    val answer = withTimeoutOrNull(1000) { query("slow-server", 3000) } ?: "default answer"
    display("2 - $answer")

    // 3 - código bloqueante ignora o cancelamento: withTimeout espera até que ele termine
    start = System.nanoTime()
    try {
        withTimeout(1000) {
            withContext(Dispatchers.IO) { queryBlocking("slow-server", 3000) }
        }
    } catch (e: TimeoutCancellationException) {
        display("3 - ${e.javaClass.simpleName}, but after three seconds")
    }

    // 4 - runInterruptible: o cancelamento da corrotina interrompe a thread que executa o código bloqueante
    start = System.nanoTime()
    try {
        withTimeout(1000) {
            runInterruptible(Dispatchers.IO) { queryBlocking("slow-server", 3000) }
        }
    } catch (e: TimeoutCancellationException) {
        display("4 - ${e.javaClass.simpleName} after one second")
    }

    // 5 - duas causas de parada: o timeout específico de cada processamento e uma parada geral
    start = System.nanoTime()
    val all = launch {
        launch { processWithTimeout("fast", 500, 1000) }
        launch { processWithTimeout("slow", 3000, 1000) }
        launch { processWithTimeout("medium", 1500, 2000) }
    }
    // o chamador solicita a parada geral após 1.200 ms
    delay(1200)
    display("5 - general stop requested")
    all.cancelAndJoin()
}

// um processamento limitado a [timeout] milissegundos, que também pode ser cancelado pelo chamador
suspend fun processWithTimeout(name: String, duration: Long, timeout: Long) {
    val message = try {
        withTimeout(timeout) { query(name, duration) }
    } catch (_: TimeoutCancellationException) {
        "$name: timeout of $timeout ms exceeded"
    } catch (e: CancellationException) {
        display("5 - $name: stopped at the caller's request")
        throw e
    }
    display("5 - $message")
}

// simula um servidor que responde após [duration] milissegundos
suspend fun query(server: String, duration: Long): String {
    try {
        delay(duration)
        return "$server answered in $duration ms"
    } catch (e: CancellationException) {
        display("  $server: operation cancelled")
        throw e
    }
}

// a mesma operação, escrita de forma bloqueante
fun queryBlocking(server: String, duration: Long): String {
    try {
        Thread.sleep(duration)
        display("  $server has finished its work")
        return "$server answered in $duration ms"
    } catch (e: InterruptedException) {
        display("  $server was interrupted")
        throw e
    }
}

// exibição com o tempo decorrido desde [start]
fun display(message: String) = println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

Resultados:

> gradlew -q run -Pmain=async19.Async19Kt
 1009 ms :   slow-server: operation cancelled
 1028 ms : 1 - TimeoutCancellationException : Timed out waiting for 1000 ms
 1001 ms :   slow-server: operation cancelled
 1002 ms : 2 - default answer
 3014 ms :   slow-server has finished its work
 3022 ms : 3 - TimeoutCancellationException, but after three seconds
 1001 ms :   slow-server was interrupted
 1003 ms : 4 - TimeoutCancellationException after one second
  504 ms : 5 - fast answered in 500 ms
 1004 ms :   slow: operation cancelled
 1005 ms : 5 - slow: timeout of 1000 ms exceeded
 1201 ms : 5 - general stop requested
 1204 ms :   medium: operation cancelled
 1204 ms : 5 - medium: stopped at the caller's request

Comentários:

  • linhas 78–85: o servidor simulado, que sinaliza seu cancelamento;
  • linhas 19–24: não esperamos uma resposta por mais de um segundo. Após um segundo, o bloco é cancelado: a operação realmente para (linha 2 dos resultados) e então [withTimeout] lança uma [TimeoutCancellationException], com uma mensagem que faz referência ao timeout (linha 3). Essa é uma diferença significativa em relação ao método [orTimeout] de [CompletableFuture], que abandonava a espera, mas deixava a operação continuar inutilmente;
  • linhas 27–30: [withTimeoutOrNull] retorna [null] se o timeout for excedido; o operador Elvis [?:] então substitui [null] por uma resposta padrão (linhas 4 e 5). É o equivalente de [completeOnTimeout], porém mais curto e, novamente, a operação é realmente encerrada;
  • linhas 32–39: o limite do cancelamento cooperativo. O bloco, limitado a um segundo, executa uma função bloqueante ([queryBlocking], linhas 89–97) em [Dispatchers.IO], que dorme por três segundos com [Thread.sleep]. Após um segundo, a corrotina de fato é cancelada, mas nada pode interromper [Thread.sleep]: a função é executada até o fim (linha 6), e só no retorno de [withContext], três segundos depois, é que [TimeoutCancellationException] é lançada (linha 7). A espera não serviu para nada;
  • linhas 42–49: para garantir que cancelar uma corrotina interrompa o código bloqueante, ele é executado com [runInterruptible(dispatcher) { … }]: a função executa o bloco no dispatcher especificado e, se a corrotina for cancelada, interrompe a thread que o executa por meio do método [interrupt()] do Java. [Thread.sleep] então lança [InterruptedException] (linha 8), que [runInterruptible] converte em [CancellationException]. Isso cria uma ponte entre o cancelamento de corrotinas e a interrupção de threads: a operação para após um segundo (linha 9). Isso funciona apenas para código bloqueante interrompível ([Thread.sleep], as esperas em [java.util.concurrent], os canais em [java.nio]…);
  • linhas 65–75: um processo que pode ser interrompido por duas razões — seu próprio timeout ou um pedido geral de parada do chamador. Ambas ocorrem na forma de uma exceção: uma [TimeoutCancellationException] disparada por [withTimeout] para o timeout e uma [CancellationException] para o cancelamento da corrotina pelo chamador. O timeout é um resultado normal do processamento, convertido em uma mensagem; já o cancelamento é sinalizado e depois relançado. As duas [catch] mensagens devem estar nessa ordem, já que [TimeoutCancellationException] deriva de [CancellationException];
  • Linhas 52–62: três processos, filhos da mesma corrotina [all]. Para o término geral, o programa Java devia criar um [CompletableFuture] adicional e anexar a ele uma continuação que cancelava cada espera; aqui, o término geral é simplesmente o cancelamento do pai, que por sua vez cancela seus filhos. O processo [fast] termina normalmente (linha 10), o processo [slow] excede seu timeout de um segundo (linhas 11 e 12), e o processo [medium], ao qual foram concedidos 2 segundos, é encerrado pelo desligamento geral aos 1.200 ms (linhas 13–15).

9.8. Relatando o progresso

Uma operação demorada muitas vezes precisa relatar seu progresso (uma barra de progresso, uma porcentagem). A abordagem mais simples é passar-lhe uma função de callback que receba as atualizações de progresso. Em Java, era um [Consumer<T>]; em Kotlin, é simplesmente um parâmetro funcional (Capítulo 7), [(Progress) -> Unit]. A operação chama essa função a cada etapa; ela não sabe nada sobre como os relatórios de progresso serão exibidos.

Em uma aplicação gráfica, surge a questão das threads: os componentes gráficos só podem ser atualizados pela thread da interface. Com corrotinas, a resposta é simples: se a corrotina que executa a operação foi iniciada em *[Dispatchers.Main], os relatórios são emitidos na thread da interface, e a função de callback pode atualizar os componentes diretamente; se a operação realiza parte de seu trabalho em outro lugar (com [withContext(Dispatchers.IO)]), ela relata seus resultados fora desse bloco, ou a função de callback volta à thread da interface com [withContext(Dispatchers.Main)] (ela é então, ela própria, uma função de suspensão, do tipo [suspend (Progress) -> Unit]). Em um programa de console, ela pode exibir a saída diretamente. O programa [Async20.kt] simula uma cópia de arquivos que o usuário pode cancelar digitando [Enter]*:

// relatando o progresso de uma operação com uma função de callback; o usuário pode cancelá-la
package async20

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.async
import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking
import kotlin.concurrent.thread

// um relatório de progresso
data class Progress(val percentage: Int, val file: String)

fun main() = runBlocking {
    println("Copy in progress, press [Enter] to cancel it")
    // a cópia é executada por uma corrotina; a função display exibe seus relatórios
    val copy = async { copyFiles(8, ::display) }
    // uma thread daemon espera o usuário pressionar [Enter] para cancelar a cópia
    thread(isDaemon = true) {
        // readlnOrNull devolve null se a entrada padrão estiver fechada: nada é cancelado
        if (readlnOrNull() != null) {
            copy.cancel()
        }
    }
    try {
        println("Copy finished: ${copy.await()} files copied")
    } catch (_: CancellationException) {
        println("Copy cancelled by the user")
    }
}

// a operação não sabe como seu progresso é exibido: ela apenas o relata
suspend fun copyFiles(nbFiles: Int, progress: ((Progress) -> Unit)? = null): Int {
    for (i in 1..nbFiles) {
        // a cópia de um arquivo
        delay(300)
        // o relatório de progresso, se o chamador quiser um
        progress?.invoke(Progress(100 * i / nbFiles, "file$i.dat"))
    }
    return nbFiles
}

// exibição dos relatórios de progresso no console: uma barra de 20 caracteres
fun display(progress: Progress) {
    val nbHashes = progress.percentage / 5
    val bar = "#".repeat(nbHashes) + ".".repeat(20 - nbHashes)
    println("[%s] %3d %% %s".format(bar, progress.percentage, progress.file))
}

Resultados sem cancelamento (a entrada padrão está fechada: [readlnOrNull()] retorna imediatamente [null]):

> gradlew -q run -Pmain=async20.Async20Kt
Copy in progress, press [Enter] to cancel it
[##..................]  12 % file1.dat
[#####...............]  25 % file2.dat
[#######.............]  37 % file3.dat
[##########..........]  50 % file4.dat
[############........]  62 % file5.dat
[###############.....]  75 % file6.dat
[#################...]  87 % file7.dat
[####################] 100 % file8.dat
Copy finished: 8 files copied

Resultados quando o usuário digita [Enter] durante a operação de cópia, após cerca de um segundo e meio (a linha vazia digitada não aparece: a entrada foi fornecida ao programa por redirecionamento de sua entrada padrão):

1
2
3
4
5
6
7
> gradlew -q run -Pmain=async20.Async20Kt
Copy in progress, press [Enter] to cancel it
[##..................]  12 % file1.dat
[#####...............]  25 % file2.dat
[#######.............]  37 % file3.dat
[##########..........]  50 % file4.dat
Copy cancelled by the user

Comentários:

  • linha 11: um relatório de progresso, uma data class contendo a porcentagem e o nome do arquivo;
  • linhas 31–39: a operação, uma função de suspensão. Seu parâmetro [progress] é do tipo [((Progress) -> Unit)?]: uma função que aceita um [Progress] e não retorna nada, ou [null] se o chamador não quiser relatórios, que é o valor padrão. Após cada arquivo, ela relata seu progresso por meio de [progress?.invoke(...)]: a chamada com [?.] não faz nada se [progress] for [null] (não é possível chamar [progress?(...)]: é preciso usar o método [invoke] do tipo funcional). A espera de 300 ms, com [delay], torna a operação cancelável;
  • linhas 42–46: exibição de um relatório: uma barra de 20 caracteres construída com [repeat]. A referência de função [::display] (linha 16) é a função de callback passada à operação;
  • linha 16: a cópia é realizada por uma corrotina na thread de [runBlocking];
  • linhas 17–21: uma thread espera o usuário digitar [Enter] e então cancela a cópia. [readlnOrNull()] é uma leitura bloqueante da entrada padrão, que não pode ser cancelada. Portanto, ela não pode ser executada em uma corrotina no escopo de [runBlocking]: a concorrência estruturada forçaria [runBlocking] a esperar o término dessa corrotina — isto é, que o usuário digite algo — mesmo depois de a cópia ter terminado. Ela é executada em uma thread criada pela função [thread] com [isDaemon = true]: uma thread daemon, que o programa descarta ao terminar. Este é um caso em que é preciso sair deliberadamente da concorrência estruturada; isso é feito com uma ferramenta explícita (uma thread daemon), e não com [GlobalScope]. O método [cancel()] de um [Job] pode ser chamado a partir de qualquer thread;
  • Linhas 24–27: o programa espera o término da cópia. O cancelamento resulta em uma [CancellationException] lançada por [await()]. Como em [Async18.kt], ela pode ser interceptada sem reiniciá-la, pois resulta do cancelamento de outra corrotina — a operação de cópia; uma falha da operação de cópia, por outro lado, se propagaria para [runBlocking] e encerraria o programa.

Uma função de callback é adequada para relatórios simples. O restante deste capítulo apresentará uma ferramenta mais geral para produzir uma sequência de valores de forma assíncrona: o fluxo ([Flow]): uma operação que retorna um [Flow<Progress>] informa seus resultados à medida que ficam disponíveis, e o chamador os coleta com [collect], no dispatcher de sua escolha.

9.9. Entrada/saída assíncrona

9.9.1. Arquivos

A E/S é a própria razão de ser da assincronia. Para arquivos, o JDK oferece duas famílias de classes, que o Kotlin usa diretamente:

  • as classes “clássicas” e bloqueantes: [Files], [BufferedReader], [BufferedWriter] e as funções de extensão que o Kotlin acrescenta a elas (Capítulo 5): [readLines], [readText], [useLines], [bufferedWriter], [writeText], [appendText]… Em um programa com corrotinas, elas são executadas no dispatcher [Dispatchers.IO], destinado a operações bloqueantes, junto com [withContext(Dispatchers.IO) { … }]: a corrotina chamadora é suspensa — sem bloquear sua thread — enquanto uma thread do dispatcher [IO] executa a operação;
  • a classe [AsynchronousFileChannel] (Java 7), cujas operações retornam um [Future] ou chamam um [CompletionHandler]. Ela raramente é usada: no Linux, na verdade realiza leituras bloqueantes em um pool de threads interno da JVM, e sua interface é desajeitada. Ela é adaptada para corrotinas com [suspendCancellableCoroutine], como o cliente TCP do programa [Async02.kt].

O programa [Async21.kt] exibe as duas famílias lendo, a partir da thread principal, o arquivo das faixas do imposto, [TaxData.txt], localizado na raiz do projeto:

1
2
3
4
5
6
7
4962:0:0
8382:0.068:291.09
14753:0.191:1322.92
23888:0.283:2668.39
38868:0.374:4846.98
47932:0.426:6883.66
0:0.481:9505.54

Cada linha contém o limite da faixa, o coeficiente [coeffR] e o coeficiente [coeffN], separados pelo caractere [:] e escritos com ponto decimal (a tabela do imposto é a de 2004 para a renda de 2003, mantida como está para este exercício fiscal). O programa é executado na pasta [09-async] (que é a pasta atual para [gradlew run]) e procura seus arquivos na pasta atual. O arquivo [taxpayers.txt], que será usado no exercício ao final do capítulo, fica no mesmo local.

// E/S de arquivos: AsynchronousFileChannel adaptado como função suspensa,
// depois E/S bloqueante comum entregue ao dispatcher IO
package async21

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.async
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.suspendCancellableCoroutine
import kotlinx.coroutines.withContext
import java.math.BigDecimal
import java.nio.ByteBuffer
import java.nio.channels.AsynchronousFileChannel
import java.nio.channels.CompletionHandler
import java.nio.file.Path
import java.nio.file.StandardOpenOption
import kotlin.coroutines.resume
import kotlin.coroutines.resumeWithException
import kotlin.io.path.appendText
import kotlin.io.path.bufferedWriter
import kotlin.io.path.deleteExisting
import kotlin.io.path.readLines
import kotlin.io.path.readText
import kotlin.io.path.useLines
import kotlin.time.measureTimedValue

val data: Path = Path.of("TaxData.txt")
val report: Path = Path.of("report-21.txt")

fun main() = runBlocking {
    // 1 - AsynchronousFileChannel (Java 7): uma leitura com callback, transformada em função suspensa
    val content = readAsynchronously(data)
    println("1 - AsynchronousFileChannel: ${content.trimEnd().lines().size} lines")

    // 2 a 7 - E/S bloqueante comum, executada no dispatcher IO
    processFiles()

    // 8 - vários arquivos lidos em paralelo: uma corrotina por arquivo, no dispatcher IO
    val files = listOf("TaxData.txt", "taxpayers.txt", "TaxData.txt").map { Path.of(it) }
    val (nbLines, duration) = measureTimedValue {
        files.map { file -> async { readSlowly(file) } }.awaitAll()
    }
    println("8 - lines read in parallel: $nbLines in ${duration.inWholeMilliseconds} ms")
}

// lê um arquivo inteiro (pequeno) com um AsynchronousFileChannel, sem bloquear uma thread
suspend fun readAsynchronously(file: Path): String =
    AsynchronousFileChannel.open(file, StandardOpenOption.READ).use { channel ->
        val buffer = ByteBuffer.allocate(channel.size().toInt())
        // a corrotina é suspensa; o método de callback a retomará
        val nbBytes = suspendCancellableCoroutine { continuation ->
            channel.read(buffer, 0, Unit, object : CompletionHandler<Int, Unit> {
                override fun completed(nbBytes: Int, attachment: Unit) = continuation.resume(nbBytes)
                override fun failed(e: Throwable, attachment: Unit) = continuation.resumeWithException(e)
            })
        }
        String(buffer.array(), 0, nbBytes, Charsets.UTF_8)
    }

// E/S bloqueante: withContext a faz ser executada por uma thread do dispatcher IO
suspend fun processFiles() = withContext(Dispatchers.IO) {
    // 2 - leitura do arquivo inteiro em uma única operação
    val lines = data.readLines()
    println("2 - readLines: ${lines.size} lines [${Thread.currentThread().name}]")

    // 3 - leitura linha a linha: useLines fornece uma sequência de linhas e fecha o arquivo
    val brackets = data.useLines { sequence -> sequence.map(TaxBracket::parse).toList() }
    println("3 - useLines: ${brackets.size} brackets, 2nd: ${brackets[1]}")

    // 4 - a sequência de linhas é lida sob demanda: o arquivo não é carregado na memória
    println("4 - useLines + count: ${data.useLines { it.count() }} lines")

    // 5 - escrita com um BufferedWriter, fechado por use
    report.bufferedWriter().use { writer ->
        writer.write("Brackets of the tax scale (exercise: 2004 tax scale on 2003 income)")
        writer.newLine()
        brackets.forEachIndexed { i, bracket ->
            val limit = if (bracket.limit.signum() == 0) "above"
            else "up to %,d €".format(bracket.limit.toInt())
            writer.write("bracket %d : %-18s rate %.1f %%".format(i + 1, limit,
                bracket.coeffR * BigDecimal(100)))
            writer.newLine()
        }
    }

    // 6 - leitura do arquivo inteiro como string
    print("5 and 6 - content of [$report]:\n${report.readText()}")

    // 7 - acréscimo ao fim do arquivo e depois exclusão
    report.appendText("end of the report\n")
    println("7 - last line: ${report.readLines().last()}")
    report.deleteExisting()
}

// uma leitura bloqueante que dura 500 ms (um arquivo em um disco lento, por exemplo)
suspend fun readSlowly(file: Path): Int = withContext(Dispatchers.IO) {
    Thread.sleep(500)
    file.readLines().size
}

// uma faixa de imposto; o arquivo usa o ponto decimal, que o BigDecimal entende
data class TaxBracket(val limit: BigDecimal, val coeffR: BigDecimal, val coeffN: BigDecimal) {
    companion object {
        fun parse(line: String): TaxBracket {
            val (limit, coeffR, coeffN) = line.split(":").map(::BigDecimal)
            return TaxBracket(limit, coeffR, coeffN)
        }
    }
}

Resultados:

> gradlew -q run -Pmain=async21.Async21Kt
1 - AsynchronousFileChannel: 7 lines
2 - readLines: 7 lines [DefaultDispatcher-worker-1]
3 - useLines: 7 brackets, 2nd: TaxBracket(limit=8382, coeffR=0.068, coeffN=291.09)
4 - useLines + count: 7 lines
5 and 6 - content of [report-21.txt]:
Brackets of the tax scale (exercise: 2004 tax scale on 2003 income)
bracket 1 : up to 4,962 €      rate 0.0 %
bracket 2 : up to 8,382 €      rate 6.8 %
bracket 3 : up to 14,753 €     rate 19.1 %
bracket 4 : up to 23,888 €     rate 28.3 %
bracket 5 : up to 38,868 €     rate 37.4 %
bracket 6 : up to 47,932 €     rate 42.6 %
bracket 7 : above              rate 48.1 %
7 - last line: end of the report
8 - lines read in parallel: [7, 7, 7] in 519 ms

Comentários:

  • Linhas 47–57: leitura com um [AsynchronousFileChannel], apresentada como uma função de suspensão que retorna o conteúdo do arquivo. O canal é um [Closeable]: a função [use] (Capítulo 3) o fecha ao final do bloco, qualquer que seja o resultado, inclusive se a corrotina for cancelada. É a mesma técnica usada no programa [Async02.kt]: [suspendCancellableCoroutine] suspende a corrotina e devolve o controle ao bloco; a operação de leitura é iniciada com um objeto de callback que retoma a corrotina com o número de bytes lidos ([resume]) ou com a exceção ([resumeWithException]). O programa Java precisava construir e concluir por conta própria um [CompletableFuture] e depois fechá-lo em uma continuação [whenComplete]; aqui, o código é lido de cima para baixo. Uma única leitura basta para um arquivo pequeno; um arquivo grande exigiria leituras sucessivas, que seriam simplesmente escritas dentro de um laço na corrotina;
  • Linha 33: a função Kotlin [lines()] divide uma string em linhas; se a string termina com uma quebra de linha, a lista termina com uma string vazia (ao contrário do método Java [lines()]). [trimEnd()] remove essa última quebra de linha;
  • linha 61: as outras operações são operações comuns de E/S bloqueante, agrupadas na função de suspensão [processFiles], cujo corpo inteiro é executado por [withContext(Dispatchers.IO)]. O nome da thread exibido na linha 3 dos resultados ([DefaultDispatcher-worker-…]) mostra que já não é a thread principal que está executando. O programa Java delegava essas operações a uma thread virtual e precisava interceptar a [IOException] dentro da lambda de um [Runnable]; em Kotlin, não existem exceções verificadas, e uma [IOException] lançada dentro do bloco de [withContext] seria relançada na corrotina chamadora;
  • linha 63: [readLines()], uma função de extensão de [Path] (pacote [kotlin.io.path]), lê o arquivo inteiro e retorna uma lista de suas linhas (em UTF-8 por padrão);
  • linha 67: [useLines] abre o arquivo, passa ao bloco uma sequência ([Sequence<String>]) de suas linhas — lidas sob demanda — e fecha o arquivo ao final do bloco: isso equivale ao laço com [readLine()] do programa Java, sem tratar [null] nem usar [try] com recurso. Cada linha é convertida em [TaxBracket] pela função [parse] do objeto companion da data class (linhas 102–106). Ela divide a linha com [split], converte os três campos em [BigDecimal] usando a referência de construtor [::BigDecimal] e os recupera por meio de uma atribuição com desestruturação. O construtor de [BigDecimal] espera um ponto decimal, independentemente do idioma da máquina. A representação produzida pelo método [toString] da data class aparece na linha 4 dos resultados;
  • linha 71: a sequência de linhas não carrega o arquivo inteiro na memória; essa é a abordagem preferível para arquivos grandes. Ela só pode ser usada dentro do bloco [useLines], já que o arquivo é fechado ao sair dele;
  • Linhas 73–82: escrita com um [BufferedWriter], obtido pela função de extensão [bufferedWriter()] e fechado (e, portanto, descarregado em disco) por [use]. O formato [%,d] insere o separador de milhares específico do idioma da máquina (uma vírgula em inglês, um espaço fino não separável em francês); o produto [bracket.coeffR * BigDecimal(100)] usa o operador [*] definido pela biblioteca padrão do Kotlin para [BigDecimal] (função de extensão [times], Capítulo 4);
  • linhas 86–92: [readText()] relê o arquivo escrito, [appendText] acrescenta uma linha a ele, [last()] retorna o último elemento da lista, e depois [deleteExisting()] exclui o arquivo;
  • linhas 38–43: vários arquivos são lidos em paralelo. Cada operação de leitura é tratada por uma corrotina ([async]), e [awaitAll()] espera os três resultados. A função [readSlowly] (linhas 96–98) simula uma leitura bloqueante de 500 ms em um disco lento; como ela é executada no dispatcher [IO], as três leituras ocupam três threads diferentes e juntas levam 500 ms, e não 1,5 s (linha 16 dos resultados). Observe que as corrotinas são lançadas por [async] sem um dispatcher: é a função chamada que escolhe, por meio de [withContext], o dispatcher adequado à sua tarefa. Esta é a regra a seguir: uma função de suspensão bloqueante deve ela mesma passar pelo dispatcher IO, para que o chamador possa invocá-la a partir de qualquer thread sem tomar nenhuma precaução especial.

O dispatcher [IO] limita por padrão a 64 o número de threads ativas ao mesmo tempo (programa [Async12.kt]). Para ler milhares de arquivos simultaneamente, é possível criar um dispatcher baseado em threads virtuais (programa [Async09.kt]); lembre-se da limitação mencionada no curso de Java: as leituras e escritas de arquivos fixam a thread virtual à sua thread hospedeira durante a operação. Para arquivos locais, isso raramente é um problema; para operações de rede, as threads virtuais e as corrotinas de fato liberam sua thread durante as esperas.

9.9.2. Rede: HttpClient

O cliente HTTP do JDK, [java.net.http.HttpClient] (Java 11), oferece duas abordagens: [send], que é bloqueante e retorna a resposta, e [sendAsync], que retorna imediatamente um [CompletableFuture] contendo a resposta. Em uma corrotina, esperamos esse [CompletableFuture] com a função de suspensão [await()] do pacote [kotlinx.coroutines.future], que já encontramos no programa [Async04.kt]: a corrotina fica suspensa até a resposta chegar, sem bloquear nenhuma thread. O Capítulo 12 examinará esse cliente em detalhes; o programa [Async22.kt] apenas compara os dois métodos consultando um pequeno servidor HTTP local, que leva um segundo para retornar a “temperatura” de uma cidade:

// HttpClient: requisições HTTP assíncronas (sendAsync + await) ou bloqueantes (send no dispatcher IO)
// a um pequeno servidor HTTP local
package async22

import com.sun.net.httpserver.HttpServer
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.async
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.future.await
import kotlinx.coroutines.runBlocking
import java.net.InetAddress
import java.net.InetSocketAddress
import java.net.URI
import java.net.URLDecoder
import java.net.URLEncoder
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
import java.util.concurrent.Executors

const val PORT = 27510
val cities = listOf("Angers", "Brest", "Colmar", "Dijon", "Évry", "Foix")
var start = System.nanoTime()

fun main() = runBlocking {
    // um servidor HTTP que leva um segundo para dar a "temperatura" de uma cidade
    val server = HttpServer.create(InetSocketAddress(InetAddress.getLoopbackAddress(), PORT), 0)
    server.createContext("/temperature") { exchange ->
        // a requisição tem a forma /temperature?city=xxx
        val city = URLDecoder.decode(exchange.requestURI.rawQuery.removePrefix("city="), Charsets.UTF_8)
        Thread.sleep(1000)
        val response = "$city : ${10 + city.length} °C".toByteArray()
        exchange.sendResponseHeaders(200, response.size.toLong())
        exchange.responseBody.use { it.write(response) }
    }
    // cada requisição recebida é processada por uma thread virtual
    server.executor = Executors.newVirtualThreadPerTaskExecutor()
    server.start()

    try {
        HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build().use { client ->
            // uma primeira requisição, para que a JVM carregue as classes do cliente antes das medições
            client.sendAsync(request("Paris"), HttpResponse.BodyHandlers.discarding()).await()

            // 1 - uma corrotina por cidade; cada uma fica suspensa até sua resposta
            start = System.nanoTime()
            val responses = cities.map { city -> async { readTemperature(client, city) } }.awaitAll()
            display("1 - sendAsync + await: $responses")

            // 2 - send é bloqueante: ele é chamado a partir do dispatcher IO
            start = System.nanoTime()
            val responses2 = cities.map { city ->
                async(Dispatchers.IO) {
                    client.send(request(city), HttpResponse.BodyHandlers.ofString()).body()
                }
            }.awaitAll()
            display("2 - send on the IO dispatcher: $responses2")
        }
    } finally {
        server.stop(0)
    }
}

// a temperatura de uma cidade: sendAsync devolve um CompletableFuture,
// await() suspende a corrotina até a resposta, sem bloquear uma thread
suspend fun readTemperature(client: HttpClient, city: String): String =
    client.sendAsync(request(city), HttpResponse.BodyHandlers.ofString()).await().body()

// a requisição GET que pede a temperatura de uma cidade
fun request(city: String): HttpRequest {
    val parameter = URLEncoder.encode(city, Charsets.UTF_8)
    return HttpRequest.newBuilder(URI.create("http://localhost:$PORT/temperature?city=$parameter")).build()
}

// exibição com o tempo decorrido desde [start]
fun display(message: String) =
    println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

Resultados:

1
2
3
> gradlew -q run -Pmain=async22.Async22Kt
 1056 ms : 1 - sendAsync + await: [Angers : 16 °C, Brest : 15 °C, Colmar : 16 °C, Dijon : 15 °C, Évry : 14 °C, Foix : 14 °C]
 1047 ms : 2 - send on the IO dispatcher: [Angers : 16 °C, Brest : 15 °C, Colmar : 16 °C, Dijon : 15 °C, Évry : 14 °C, Foix : 14 °C]

Comentários:

  • Linhas 26–38: o servidor. A JVM contém um pequeno servidor HTTP, que é a classe [HttpServer] do módulo [jdk.httpserver] (pacote [com.sun.net.httpserver]). Ele é criado no endereço local ([getLoopbackAddress()]) e na porta 27510; [createContext] associa um handler — uma lambda que recebe a troca HTTP — ao caminho [/temperature] (a interface Java [HttpHandler] tem apenas um método: a lambda Kotlin é convertida nela; trata-se de uma conversão SAM, Capítulo 7). O handler decodifica o parâmetro [city] a partir do endereço solicitado ([removePrefix] remove a parte inicial [city=]), espera um segundo e então envia a resposta; [toByteArray()] codifica a string em UTF-8. A linha 37 faz com que cada requisição seja processada por uma thread virtual: um servidor configurado dessa forma pode atender milhares de clientes em espera. Observe a notação [server.executor = …]: o Kotlin apresenta o par de métodos Java [getExecutor] / [setExecutor] como uma propriedade, assim como [getRequestURI()] se torna [requestURI] e [getResponseBody()] se torna [responseBody];
  • Linha 41: o cliente é criado por um construtor ([newBuilder]), que aqui define a versão do protocolo. A partir do Java 21, ele implementa [AutoCloseable]: a função [use] o fecha ao final do bloco. Uma requisição inicial serve para “aquecer” a JVM: o primeiro uso de um cliente carrega numerosas classes, o que distorceria a medição seguinte em algumas centenas de milissegundos;
  • linhas 64–67: a função de suspensão [readTemperature]. [sendAsync(request, handler)] envia a requisição e retorna imediatamente um [CompletableFuture<HttpResponse<String>>]; o handler de corpo [BodyHandlers.ofString()] especifica que o corpo da resposta deve ser lido como uma string. [await()] suspende a corrotina até a resposta chegar, e o corpo é armazenado ([body()]). Onde o programa Java encadeava uma continuação ([thenApply(HttpResponse::body)]), simplesmente escrevemos as chamadas uma após a outra;
  • linhas 45–48: seis corrotinas, uma por cidade, enviam suas requisições ao mesmo tempo; as respostas chegam juntas após um segundo (linha 2 dos resultados). Durante a espera, nenhuma thread aguarda a resposta: o cliente monitora suas conexões por meio de uma thread “seletora”, que conclui o [CompletableFuture]; a retomada das corrotinas fica então a cargo do dispatcher de [runBlocking], isto é, da thread principal. O programa Java precisava combinar os [CompletableFuture] com [allOf] e depois ler seus resultados com [resultNow]; [awaitAll()] faz as duas coisas;
  • Linhas 50–57: [send] é bloqueante; ele é chamado a partir de seis corrotinas executadas no dispatcher [IO], cada uma das quais ocupa uma thread durante a espera. O resultado é o mesmo: um segundo para as seis requisições (linha 3). Essa abordagem funciona para algumas requisições; para milhares delas, [sendAsync] e [await()] não ocupam nenhuma thread durante a espera;
  • linhas 59–60: o servidor é encerrado ao final do programa, qualquer que seja o resultado; o parâmetro de [stop] é o número de segundos concedidos para que as trocas em andamento terminem;
  • linhas 70–72: a requisição GET. [URLEncoder.encode] codifica os caracteres que não podem aparecer como estão em um endereço (o [É] de Évry), e o servidor os decodifica com [URLDecoder.decode];
  • a variável [start] (linha 23) é uma variável de alto nível modificável ([var]), reinicializada com a hora atual antes de cada medição; a função [display] exibe o tempo decorrido desde [start], como nos programas anteriores.

Guarde a seguinte regra: diante de uma API Java que retorna um CompletableFuture, uma corrotina espera por ele com await()**; diante de uma API bloqueante, ela a chama no dispatcher [IO]. Nos dois casos, o código da corrotina permanece sequencial.

9.10. Fluxos assíncronos de valores

Uma operação assíncrona retorna um resultado após certo tempo. Uma sequência ([Sequence], Capítulo 5) ou um iterador retorna uma sequência de valores, produzidos sob demanda. Às vezes é preciso combinar as duas coisas: uma sequência de valores em que cada um exige uma espera antes de ser produzido. É o caso das linhas de um arquivo grande, das linhas do resultado de uma consulta SQL, das mensagens que chegam por uma conexão de rede, das leituras de sensores e assim por diante. O curso de Java apresentou dois modelos: o modelo “pull”, em que o consumidor solicita o próximo valor e espera que ele chegue (um [Stream] em que cada valor bloqueia, lido por uma thread virtual), e o modelo “push”, em que o produtor envia valores a seus assinantes, que controlam a vazão (as interfaces [java.util.concurrent.Flow] do Java 9 e a classe [SubmissionPublisher]).

O Kotlinx.coroutines oferece duas ferramentas que cobrem esses dois modelos:

  • o fluxo ([Flow<T>], pacote [kotlinx.coroutines.flow]): uma sequência de valores produzida por uma função de suspensão, a pedido do consumidor. É o equivalente assíncrono de uma sequência, com operadores ([map], [filter], [take]…) que são, eles próprios, funções de suspensão. Um fluxo é passivo: nada é produzido até que alguém o colete, e cada coleta reinicia a produção;
  • o canal ([Channel<T>]), já encontrado no programa [Async14.kt]: uma fila entre corrotinas, em que o produtor envia ([send]) e o consumidor recebe ([receive]), cada um sendo suspenso se o outro não acompanhar o ritmo. Um canal é “quente”: o produtor opera independentemente do consumidor. Os fluxos compartilhados ([SharedFlow], [StateFlow]) também são quentes.

O C# oferece os fluxos assíncronos [IAsyncEnumerable<T>] para o mesmo fim, produzidos por [yield return] e consumidos por [await foreach]: o [Flow] do Kotlin é o equivalente.

9.10.1. Fluxos

Um fluxo é criado pela função [flow { … }], cujo bloco é uma função de suspensão que emite seus valores com [emit(value)]; ele é consumido pela função de suspensão [collect { value -> … }], que executa seu bloco para cada valor emitido. O programa [Async23.kt] incorpora o programa Java que gerava medições — uma a cada 200 ms — na forma de um [Stream<Measurement>]:

// uma sequência de valores produzidos com esperas: um flow do kotlinx.coroutines (Flow)
package async23

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.cancelAndJoin
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.filter
import kotlinx.coroutines.flow.first
import kotlinx.coroutines.flow.flow
import kotlinx.coroutines.flow.map
import kotlinx.coroutines.flow.onEach
import kotlinx.coroutines.flow.take
import kotlinx.coroutines.flow.toList
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import java.text.NumberFormat

var start = System.nanoTime()

fun main() = runBlocking {
    // 1 - cada valor é processado assim que é produzido
    start = System.nanoTime()
    readMeasurements("sensor-1", 4).collect { measurement -> display("1 - received $measurement") }

    // 2 - a coleta pode ser interrompida antes do fim: o produtor não produz os valores seguintes
    start = System.nanoTime()
    val hot = readMeasurements("sensor-2", 100)
        .onEach { measurement -> display("2 - received $measurement") }
        .first { measurement -> measurement.value >= 22 }
    display("2 - first measurement of at least 22 °C: $hot")

    // 3 - cancelamento: a corrotina que coleta o flow é cancelada após 700 ms
    start = System.nanoTime()
    val reader = launch {
        try {
            readMeasurements("sensor-3", 100).collect { measurement -> display("3 - received $measurement") }
        } catch (e: CancellationException) {
            display("3 - reading cancelled")
            throw e
        }
    }
    delay(700)
    reader.cancelAndJoin()

    // 4 - operadores transformam o flow: filtragem, transformação, limitação
    start = System.nanoTime()
    val high = readMeasurements("sensor-4", 100)
        .filter { measurement -> measurement.value > 21 }
        .map { measurement -> format(measurement.value) }
        .take(4)
        .toList()
    display("4 - measurements greater than 21: ${high.joinToString(" ; ", "[", "]")}")
}

// um produtor: uma medição a cada 200 ms, produzida apenas quando o coletor a solicita
fun readMeasurements(sensor: String, count: Int): Flow<Measurement> = flow {
    try {
        for (i in 1..count) {
            // esperando a próxima medição
            delay(200)
            // emit suspende o produtor até que o coletor tenha processado o valor
            emit(Measurement(sensor, i, 19.5 + i * 0.75))
        }
    } finally {
        // executado no fim normal, após a coleta ser interrompida ou em caso de cancelamento
        println("          $sensor: end of production")
    }
}

// uma medição
data class Measurement(val sensor: String, val number: Int, val value: Double) {
    override fun toString() = "$sensor no. $number : ${format(value)} °C"
}

// um número real no formato do idioma da máquina, sem casas decimais inúteis
fun format(value: Double): String = NumberFormat.getInstance().format(value)

// exibição com o tempo decorrido desde [start]
fun display(message: String) =
    println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

Resultados:

> gradlew -q run -Pmain=async23.Async23Kt
  413 ms : 1 - received sensor-1 no. 1 : 20.25 °C
  615 ms : 1 - received sensor-1 no. 2 : 21 °C
  816 ms : 1 - received sensor-1 no. 3 : 21.75 °C
 1020 ms : 1 - received sensor-1 no. 4 : 22.5 °C
          sensor-1: end of production
  241 ms : 2 - received sensor-2 no. 1 : 20.25 °C
  451 ms : 2 - received sensor-2 no. 2 : 21 °C
  652 ms : 2 - received sensor-2 no. 3 : 21.75 °C
  859 ms : 2 - received sensor-2 no. 4 : 22.5 °C
          sensor-2: end of production
  864 ms : 2 - first measurement of at least 22 °C: sensor-2 no. 4 : 22.5 °C
  242 ms : 3 - received sensor-3 no. 1 : 20.25 °C
  450 ms : 3 - received sensor-3 no. 2 : 21 °C
  651 ms : 3 - received sensor-3 no. 3 : 21.75 °C
          sensor-3: end of production
  744 ms : 3 - reading cancelled
          sensor-4: end of production
 1262 ms : 4 - measurements greater than 21: [21.75 ; 22.5 ; 23.25 ; 24]

Comentários:

  • Linhas 57–67: o produtor. A função [readMeasurements] não é uma função bloqueante: ela retorna imediatamente um [Flow<Measurement>] sem produzir nada. O bloco de [flow] só será executado quando um consumidor coletar o fluxo. Ele espera 200 ms com [delay] e depois envia uma medição com [emit]; [emit] é uma função de suspensão que chama o bloco [collect] do consumidor e só devolve o controle depois que o valor foi processado: cada medição é processada antes que a seguinte seja produzida. O bloco [finally] é o “[finally] do produtor”: ele substitui a ação [onClose] do bloco Java de [Stream] e é executado independentemente de como a coleta termine;
  • Linha 24: cada medição é processada assim que é produzida: uma a cada 200 ms (linhas 2–5 dos resultados; a primeira chega um pouco depois, enquanto a JVM carrega as classes do fluxo), e então o produtor termina (linha 6). Não há fluxos a fechar: o fim da coleta de dados marca o fim da produção;
  • linhas 26–31: o operador [onEach] executa uma ação para cada valor que passa, e a função de suspensão [first { condition }] coleta o fluxo até o primeiro valor que satisfaz a condição, retorna esse valor e interrompe a coleta. O produtor não produz as 96 medições restantes: seu [emit] lançou uma exceção interna de cancelamento, que o interrompeu e executou seu [finally] (linha 11 dos resultados). Para obter o mesmo resultado, o programa Java precisava percorrer o stream por meio de seu iterador e sair com [break];
  • linhas 33–44: o cancelamento. O fluxo é coletado por outra corrotina, que a corrotina principal cancela após 700 ms com [cancelAndJoin()]. O [delay] da quarta medição é cancelado: ele dispara uma [CancellationException] que atravessa o produtor (seu [finally] é executado, linha 16 dos resultados), depois [collect], e então chega ao [catch] do leitor (linha 17), que a relança, como esperado. Nenhuma interrupção de thread é necessária: trata-se do cancelamento cooperativo das corrotinas;
  • linhas 46–53: os operadores [filter], [map] e [take] transformam o fluxo e retornam um novo fluxo; eles têm o nome das funções para coleções e sequências (Capítulo 5). A função de suspensão [toList()] coleta o fluxo em uma lista. [take(4)] interrompe a coleta após quatro valores: o produtor, configurado para 100 medições, para na sexta (o resultado fica disponível após aproximadamente 6 × 200 ms). O programa Java coletava seis medições e as filtrava; aqui, o fluxo poderia ser infinito;
  • linhas 72–77: o método [toString] da data class [Measurement] é redefinido para uma exibição mais compacta; [NumberFormat.getInstance()] formata o número real de acordo com o idioma da máquina, sem casas decimais desnecessárias ([21], [21.75]).

É importante distinguir os dois tipos de funções da API de fluxos:

  • operadores intermediários ([map], [filter], [take], [onEach], [flowOn], [buffer], [catch]…) não são funções de suspensão: eles retornam imediatamente um novo fluxo, que descreve um processo, sem executar nada;
  • operadores terminais ([collect], [toList], [first], [single], [reduce], [fold], [count]…) são funções de suspensão: eles disparam a produção e esperam que ela termine.

Esse é o modelo usado nas sequências do Kotlin (e no [Stream] do Java), mas agora cada etapa pode esperar sem bloquear uma thread. O programa [Async20.kt] informava o progresso de uma operação por meio de uma função de callback; uma operação também pode retornar um [Flow<Progress>] e informar seu progresso em tempo real, com o chamador coletando esses relatórios com [collect].

9.10.2. Fluxos frios, flowOn, buffer e catch

O programa [Async24.kt] demonstra quatro propriedades dos fluxos: eles são frios, seu produtor pode trocar de dispatcher, um buffer pode desacoplar o produtor do consumidor, e as exceções ocorridas a montante podem ser interceptadas:

// os flows (Flow) são frios; flowOn, buffer e catch
package async24

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.buffer
import kotlinx.coroutines.flow.catch
import kotlinx.coroutines.flow.flow
import kotlinx.coroutines.flow.flowOn
import kotlinx.coroutines.flow.map
import kotlinx.coroutines.flow.onEach
import kotlinx.coroutines.flow.toList
import kotlinx.coroutines.runBlocking
import kotlin.time.measureTime

var start = System.nanoTime()

fun main() = runBlocking {
    // 1 - um flow é frio: criá-lo não produz nada; cada coleta reinicia a produção
    start = System.nanoTime()
    val values = counter("A", 3)
    display("1 - flow created")
    display("1 - 1st collection: ${values.toList()}")
    display("1 - 2nd collection: ${values.toList()}")

    // 2 - flowOn: o produtor (e o que precede flowOn) é executado em outro dispatcher
    start = System.nanoTime()
    counter("B", 2)
        .map { value -> "$value (transformed by ${threadName()})" }
        .flowOn(Dispatchers.Default)
        .collect { value -> display("2 - received $value, collected by ${threadName()}") }

    // 3 - sem buffer: produção (200 ms) e processamento (300 ms) se sucedem
    val withoutBuffer = measureTime {
        counter("C", 5, trace = false).collect { delay(300) }
    }
    println("3 - without a buffer: ${withoutBuffer.inWholeMilliseconds} ms")
    // com buffer: o produtor trabalha enquanto o coletor processa
    val withBuffer = measureTime {
        counter("D", 5, trace = false).buffer().collect { delay(300) }
    }
    println("3 - with a buffer: ${withBuffer.inWholeMilliseconds} ms")

    // 4 - catch intercepta as exceções do upstream e pode emitir um valor de substituição
    start = System.nanoTime()
    readings()
        .onEach { value -> display("4 - received $value") }
        .catch { e ->
            display("4 - error caught: ${e.message}")
            emit(-1)
        }
        .collect { value -> display("4 - collected $value") }
}

// um flow de [count] inteiros, um a cada 200 ms
fun counter(name: String, count: Int, trace: Boolean = true): Flow<Int> = flow {
    if (trace) display("    $name: start of production, by ${threadName()}")
    for (i in 1..count) {
        delay(200)
        emit(i)
    }
}

// um flow que falha após dois valores
fun readings(): Flow<Int> = flow {
    emit(10)
    emit(20)
    throw IllegalStateException("sensor unplugged")
}

fun threadName(): String = Thread.currentThread().name

// exibição com o tempo decorrido desde [start]
fun display(message: String) =
    println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

Resultados:

> gradlew -q run -Pmain=async24.Async24Kt
    3 ms : 1 - flow created
   45 ms :     A: start of production, by main
  673 ms : 1 - 1st collection: [1, 2, 3]
  673 ms :     A: start of production, by main
 1275 ms : 1 - 2nd collection: [1, 2, 3]
   37 ms :     B: start of production, by DefaultDispatcher-worker-1
  247 ms : 2 - received 1 (transformed by DefaultDispatcher-worker-1), collected by main
  448 ms : 2 - received 2 (transformed by DefaultDispatcher-worker-1), collected by main
3 - without a buffer: 2513 ms
3 - with a buffer: 1712 ms
   26 ms : 4 - received 10
   27 ms : 4 - collected 10
   27 ms : 4 - received 20
   27 ms : 4 - collected 20
   27 ms : 4 - error caught: sensor unplugged
   27 ms : 4 - collected -1

Comentários:

  • linhas 57–61: o fluxo de teste: um inteiro a cada 200 ms. O parâmetro [trace] (valor padrão [true]) exibe o início da produção e a thread que a executa;
  • Linhas 20–25: criar o fluxo não produz nada (linha 2 dos resultados: nenhum rastro do produtor). Cada coleta ([toList()]) reexecuta o bloco de [flow] desde o início (linhas 3 e 5): um fluxo é uma receita de produção, e não uma fonte de valores já em trânsito. Essa é a diferença em relação a um canal, que será discutido adiante;
  • linhas 27–32: por padrão, o produtor é executado na corrotina do coletor, em seu dispatcher: a linha 3 dos resultados mostra que o produtor da Parte 1 era executado na thread [main]. O operador [flowOn(dispatcher)] faz tudo o que o precede (o produtor e [map]) ser executado em outro dispatcher, neste caso [Dispatchers.Default], enquanto a coleta permanece na thread [main] (linhas 7–9). Essa é a ferramenta para aplicações gráficas: a produção (leitura de um banco de dados ou da rede) ocorre em [Dispatchers.IO] ou [Default], enquanto a coleta dos dados (a exibição) ocorre na thread da interface. Nunca se deve trocar o dispatcher dentro do bloco de [flow] com [withContext] em torno de um [emit]: a biblioteca detecta isso e lança uma [IllegalStateException]; [flowOn] é a única forma correta;
  • linhas 34–43: sem buffer, [emit] espera o coletor processar o valor: a produção (200 ms) e o processamento (300 ms) ocorrem em sequência, e os cinco valores levam 5 × 500 = 2.500 ms (linha 10 dos resultados). O operador [buffer()] coloca um canal entre o produtor e o coletor, que passam então a ser executados em duas corrotinas diferentes: o produtor prepara o valor seguinte enquanto o coletor processa o anterior, e o processo inteiro leva 200 + 5 × 300 = 1.700 ms (linha 11). A função [measureTime] da biblioteca padrão mede a duração de um bloco. O buffer tem uma capacidade (64 valores por padrão; use [buffer(10)] para outro valor): quando ele está cheio, o produtor fica suspenso até que uma vaga seja liberada. Esse é o backpressure dos fluxos reativos, obtido sem nenhum protocolo de requisição: um produtor suspenso deixa de produzir;
  • linhas 66–69: um fluxo que falha após dois valores;
  • Linhas 45–53: o operador [catch] captura as exceções lançadas a montante (pelo produtor e pelos operadores anteriores, neste caso [onEach]). Seu bloco recebe a exceção e pode exibi-la, retornar valores de substituição (aqui, [-1], linha 17 dos resultados) ou lançar outra exceção. Ele não intercepta as exceções a jusante (as do bloco [collect]): para essas, a coleta é envolvida por um [try / catch] padrão, que também intercepta as exceções a montante. Diferentemente de um [catch (e: Exception)], o operador [catch] deixa passar a exceção de término da corrotina que coleta o fluxo: ele não impede o término.

Outros operadores costumam ser úteis: [transform] (emite zero, um ou mais valores para cada valor recebido), [onCompletion] (uma ação ao final do fluxo, com sua causa, se houver), [retry] (retoma a produção após um erro), [distinctUntilChanged] (ignora um valor igual ao anterior), [conflate] (um coletor lento recebe apenas o valor mais recente), [scan] (resultados sucessivos de uma acumulação), [combine] e [zip] (combinam dois fluxos).

9.10.3. Canais: um produtor, um consumidor

Um fluxo é “frio”: sua produção é responsabilidade do consumidor. Quando a fonte produz em seu próprio ritmo, seja ou não lida (um sensor, mensagens recebidas, eventos), é necessário um fluxo “quente”. O mais simples é o canal ([Channel<T>], pacote [kotlinx.coroutines.channels]), uma fila para corrotinas: ele é o equivalente de uma [BlockingQueue] (Capítulo 8), em que as operações que bloqueavam a thread ([put], [take]) se tornam funções de suspensão ([send], [receive]). Sua capacidade é definida na criação:

  • [Channel<T>()] ([Channel.RENDEZVOUS]): sem buffer; cada [send] espera um [receive] (programa [Async14.kt]);
  • [Channel<T>(n)]: um buffer contendo [n] valores; [send] só espera quando o buffer está cheio;
  • [Channel<T>(Channel.UNLIMITED)]: um buffer ilimitado; [send] nunca espera (com o risco de encher a memória);
  • [Channel<T>(Channel.CONFLATED)]: uma única vaga; um novo valor substitui aquele que não foi lido.

O programa [Async25.kt] faz um consumidor lento ler as medições de um produtor que começa a trabalhar sem esperá-lo:

// um canal (Channel) entre um produtor e um consumidor: um flow quente, com buffer
package async25

import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.channels.Channel
import kotlinx.coroutines.channels.ReceiveChannel
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import java.text.NumberFormat

var start = System.nanoTime()

fun main() = runBlocking {
    // 1 - o produtor começa imediatamente, quer alguém leia o canal ou não
    start = System.nanoTime()
    val measurements = produceMeasurements("sensor-1", 5)
    delay(700)
    display("consumer: start of reading")
    // o loop for recebe os valores um a um, até que o canal seja fechado
    for (measurement in measurements) {
        display("consumer: received $measurement")
        // o consumidor é mais lento que o produtor
        delay(500)
    }
    display("1 - the channel is closed: end of reading")

    // 2 - o consumidor para de ler: cancel() fecha o canal, o produtor para
    start = System.nanoTime()
    val measurements2 = produceMeasurements("sensor-2", 100)
    repeat(2) { display("2 - received ${measurements2.receive()}") }
    measurements2.cancel()
    display("2 - reading abandoned")
}

// lança um produtor no escopo do chamador e devolve o canal onde ele envia suas medições
fun CoroutineScope.produceMeasurements(sensor: String, count: Int): ReceiveChannel<Measurement> {
    // um canal que pode conter 2 valores enviados mas ainda não recebidos
    val channel = Channel<Measurement>(capacity = 2)
    launch {
        try {
            for (i in 1..count) {
                delay(200)
                // send suspende o produtor enquanto o buffer estiver cheio
                channel.send(Measurement(sensor, i, 19.5 + i * 0.75))
                display("    producer: measurement no. $i sent")
            }
        } finally {
            // o fechamento sinaliza ao consumidor que não haverá mais valores
            channel.close()
            display("    producer: end of production")
        }
    }
    return channel
}

// uma medição
data class Measurement(val sensor: String, val number: Int, val value: Double) {
    override fun toString() = "$sensor no. $number : ${NumberFormat.getInstance().format(value)} °C"
}

// exibição com o tempo decorrido desde [start]
fun display(message: String) =
    println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

Resultados:

> gradlew -q run -Pmain=async25.Async25Kt
  232 ms :     producer: measurement no. 1 sent
  501 ms :     producer: measurement no. 2 sent
  715 ms : consumer: start of reading
  739 ms : consumer: received sensor-1 no. 1 : 20.25 °C
  739 ms :     producer: measurement no. 3 sent
 1240 ms : consumer: received sensor-1 no. 2 : 21 °C
 1240 ms :     producer: measurement no. 4 sent
 1740 ms : consumer: received sensor-1 no. 3 : 21.75 °C
 1741 ms :     producer: measurement no. 5 sent
 1743 ms :     producer: end of production
 2261 ms : consumer: received sensor-1 no. 4 : 22.5 °C
 2762 ms : consumer: received sensor-1 no. 5 : 23.25 °C
 3263 ms : 1 - the channel is closed: end of reading
  202 ms :     producer: measurement no. 1 sent
  206 ms : 2 - received sensor-2 no. 1 : 20.25 °C
  409 ms :     producer: measurement no. 2 sent
  409 ms : 2 - received sensor-2 no. 2 : 21 °C
  419 ms : 2 - reading abandoned
  614 ms :     producer: end of production

Comentários:

  • Linhas 37–54: o produtor. A função [produceMeasurements] é uma extensão de [CoroutineScope]: ela lança uma corrotina dentro do escopo do chamador ([launch] se aplica ao receptor implícito [this], o escopo) e retorna imediatamente o canal para o qual essa corrotina enviará suas medições. Essa é a convenção do kotlinx.coroutines: uma função que lança corrotinas e retorna sem esperar por elas é uma extensão de CoroutineScope; uma função que espera o término de seu trabalho é uma função de suspensão. O tipo retornado, [ReceiveChannel<Measurement>], é a parte “receber” do canal: o chamador só pode receber;
  • linha 39: um canal com capacidade de 2;
  • linha 45: [send] coloca a medição no buffer, ou suspende o produtor se ele estiver cheio;
  • linhas 49–50: ao final da produção — normal ou não — o produtor fecha o canal. Fechar o canal não apaga os valores do buffer: o consumidor ainda os receberá e só depois saberá que o canal está fechado;
  • Linhas 17–19: o produtor começa imediatamente, enquanto o consumidor só lerá o canal 700 ms depois. Nesse intervalo, as medições nº 1 e nº 2 enchem o buffer (linhas 2–3 dos resultados); a medição nº 3, pronta por volta de 600 ms, não pode ser entregue: [send] suspende o produtor. Assim que o consumidor recebe a medição nº 1, uma vaga é liberada e a medição nº 3 é entregue (linhas 5–6). Em seguida, o produtor passa a acompanhar o ritmo do consumidor, enviando uma medição a cada 500 ms: esse é o backpressure, obtido simplesmente pela suspensão de [send];
  • linhas 21–26: um canal é processado com um laço [for], que recebe os valores um a um e termina quando o canal está fechado e vazio. O produtor terminou em 1.743 ms (linha 11 dos resultados); o consumidor ainda lê as duas medições do buffer (linhas 12–13) antes de sair do laço (linha 14);
  • linhas 28–33: [receive()] recebe um valor por vez; após duas medições, o consumidor para de ler com [cancel()], que fecha o canal e apaga seu buffer. O próximo [send] do produtor então dispara uma [CancellationException], que encerra sua corrotina após executar [finally] (última linha dos resultados). Sem esse [cancel()], o produtor — bloqueado por um buffer cheio — nunca terminaria, e [runBlocking], que espera seus filhos, tampouco. Também é possível percorrer um canal com [channel.consumeEach { … }], que cancela o canal ao sair do bloco, qualquer que seja o motivo.

O Kotlinx.coroutines oferece uma função, [produce], que faz o que [produceMeasurements] faz (lança uma corrotina que escreve em um canal e retorna o canal), mas ela ainda está marcada como experimental: usá-la dispara esse aviso, de modo que ocorre um erro com a opção [allWarningsAsErrors] em nosso projeto:

1
2
3
4
error: warnings found and -Werror specified
T.kt:4:13: warning: this declaration needs opt-in. Its usage should be marked with '@kotlinx.coroutines.ExperimentalCoroutinesApi' or '@OptIn(kotlinx.coroutines.ExperimentalCoroutinesApi::class)'
    val c = produce(capacity = 2) { send(1); send(2) }
            ^^^^^^^

Neste curso, não usamos a API experimental (seria preciso aceitá-la explicitamente com a anotação [@OptIn(ExperimentalCoroutinesApi::class)], e ela poderia mudar em uma versão futura): o canal e o [launch] escrito à mão fazem a mesma coisa em poucas linhas.

Um canal entrega cada valor a um único consumidor: se várias corrotinas leem o mesmo canal, elas dividem os valores entre si. É isso que se precisa para distribuir trabalho entre workers (veremos isso na seção sobre paralelismo limitado), mas não para transmitir valores a vários assinantes.

9.10.4. Fluxos compartilhados: vários assinantes

Para transmitir cada valor a todos os assinantes, o kotlinx.coroutines oferece o fluxo compartilhado: [MutableSharedFlow<T>], no qual o publicador transmite com [emit], é visto pelos assinantes como um [SharedFlow<T>], que eles coletam como qualquer outro fluxo. Ele é o equivalente do [SubmissionPublisher] do curso de Java, e o programa [Async26.kt] usa o mesmo exemplo: seis medições publicadas para dois assinantes, um display rápido que cancela a assinatura quando a temperatura ultrapassa 22 °C e um arquivo lento:

// um flow quente transmitido a vários assinantes: MutableSharedFlow (o equivalente a SubmissionPublisher)
package async26

import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.filterNotNull
import kotlinx.coroutines.flow.first
import kotlinx.coroutines.flow.takeWhile
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import java.text.NumberFormat

val start = System.nanoTime()

fun main() = runBlocking {
    // cada valor emitido é entregue a todos os assinantes; buffer de 2 valores para o mais lento
    // o valor null sinaliza o fim da publicação
    val publisher = MutableSharedFlow<Measurement?>(extraBufferCapacity = 2)

    // a tela, rápida, cancela a assinatura assim que uma medição atinge 22 °C
    launch {
        publisher.untilTheEnd().first { measurement ->
            display("  screen: received $measurement")
            measurement.value >= 22
        }
        display("  screen: threshold reached, unsubscribing")
    }
    // o arquivo, lento, processa cada medição em 500 ms
    launch {
        publisher.untilTheEnd().collect { measurement ->
            display("  archive: received $measurement")
            delay(500)
        }
        display("  archive: end of the flow")
    }

    // esperamos que os dois assinantes estejam registrados: um shared flow não guarda nada para os ausentes
    publisher.subscriptionCount.first { count -> count == 2 }
    for (i in 1..6) {
        delay(200)
        // emit suspende o publicador se não houver mais espaço no buffer do assinante mais lento
        publisher.emit(Measurement("sensor-1", i, 19.5 + i * 0.75))
        display("publisher: measurement no. $i published")
    }
    display("publisher: end of publication")
    publisher.emit(null)
}

// um shared flow nunca termina: a coleta é interrompida no valor null
fun Flow<Measurement?>.untilTheEnd(): Flow<Measurement> = takeWhile { it != null }.filterNotNull()

// uma medição
data class Measurement(val sensor: String, val number: Int, val value: Double) {
    override fun toString() = "$sensor no. $number : ${NumberFormat.getInstance().format(value)} °C"
}

// exibição com o tempo decorrido desde o início
fun display(message: String) =
    println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

Resultados:

> gradlew -q run -Pmain=async26.Async26Kt
  443 ms : publisher: measurement no. 1 published
  504 ms :   screen: received sensor-1 no. 1 : 20.25 °C
  505 ms :   archive: received sensor-1 no. 1 : 20.25 °C
  688 ms : publisher: measurement no. 2 published
  688 ms :   screen: received sensor-1 no. 2 : 21 °C
  894 ms : publisher: measurement no. 3 published
  895 ms :   screen: received sensor-1 no. 3 : 21.75 °C
 1005 ms :   archive: received sensor-1 no. 2 : 21 °C
 1096 ms : publisher: measurement no. 4 published
 1096 ms :   screen: received sensor-1 no. 4 : 22.5 °C
 1096 ms :   screen: threshold reached, unsubscribing
 1506 ms :   archive: received sensor-1 no. 3 : 21.75 °C
 1507 ms : publisher: measurement no. 5 published
 2008 ms :   archive: received sensor-1 no. 4 : 22.5 °C
 2008 ms : publisher: measurement no. 6 published
 2008 ms : publisher: end of publication
 2509 ms :   archive: received sensor-1 no. 5 : 23.25 °C
 3010 ms :   archive: received sensor-1 no. 6 : 24 °C
 3511 ms :   archive: end of the flow

Comentários:

  • Linha 19: o publicador, um fluxo compartilhado de medições. O parâmetro [extraBufferCapacity = 2] dota-o de um buffer de 2 valores: o publicador pode estar até 2 valores à frente do assinante mais lento. O tipo do valor é [Measurement?]: o valor [null] servirá para sinalizar o fim da publicação;
  • linhas 21–27: a tela é uma corrotina que coleta o fluxo de dados até a primeira leitura de pelo menos 22 °C, com [first] (programa [Async23.kt]): a assinatura começa com a coleta de dados e termina com ela. Não há [onSubscribe], nem [request(1)], nem [cancel()]: todo o protocolo de fluxo de dados reativo consiste em coletar os dados e depois parar;
  • linhas 29–35: o arquivo processa cada medição em 500 ms. Durante esse processamento, a coleta de dados não avança: é isso que regula a vazão, como o [request(1)] do assinante Java;
  • Linha 51: um fluxo compartilhado nunca termina: um assinante que o coleta espera indefinidamente pelos próximos valores até que sua corrotina seja cancelada. Não há equivalente ao método [close()] do publicador Java. Para sinalizar o fim, emite-se um valor predefinido — neste caso, [null]. A função de extensão [untilTheEnd] interrompe a coleta nesse valor ([takeWhile]) e retorna um [Flow<Measurement>] ([filterNotNull] muda o tipo dos valores, de [Measurement?] para [Measurement]);
  • Linha 39: um fluxo compartilhado não retém nada para assinantes ausentes: um valor publicado quando ninguém está inscrito é perdido (a menos que o fluxo seja instruído a reenviar alguns deles aos novos assinantes, com o parâmetro [replay]). A propriedade [subscriptionCount] é um fluxo do número de assinantes: esperamos até que ele chegue a 2 antes de publicar. Sem essa precaução, os dois assinantes, lançados por [launch], ainda não teriam começado a coletar dados no momento da primeira transmissão;
  • Linhas 40–47: o publicador publica uma medição a cada 200 ms. [emit] é uma função de suspensão: quando o buffer do assinante mais lento está cheio, ela espera que uma vaga seja liberada. A medição nº 5, pronta por volta de 1.300 ms, só é publicada em 1.507 ms (linha 14 dos resultados), quando o arquivo já pegou a medição nº 3. Esse é o backpressure: o publicador é desacelerado ao ritmo do assinante mais lento;
  • os resultados são os do programa Java: a tela processa cada medição assim que é publicada e cancela a assinatura na medição nº 4 (linhas 11–12), enquanto o arquivo, que leva 500 ms por medição, fica para trás e recebe as seis medições, seguidas do fim do fluxo (linha 20). O programa termina quando os dois assinantes terminam: eles são filhos de [runBlocking], que os espera.

Um tipo específico de fluxo compartilhado é amplamente usado: o fluxo de estado ([MutableStateFlow<T>] / [StateFlow<T>]). Ele sempre tem um valor — o valor atual — que pode ser lido e modificado por meio de sua propriedade [value] ([state.value = "connected"]); seus assinantes recebem o valor atual assim que se inscrevem e, depois, cada novo valor (um valor igual ao anterior não é emitido, e um assinante lento recebe apenas o mais recente). Essa é a ferramenta usada pelas aplicações gráficas e Android para representar o estado de uma tela: a lógica de negócio modifica o estado, a interface do usuário o coleta, e a tela é redesenhada a cada mudança. É o equivalente assíncrono das propriedades observáveis tratadas no Capítulo 7.

Pontos principais:

Ferramenta
Uso
[Flow] (frio)
uma sequência de valores gerados sob demanda para um consumidor: linhas de um arquivo, resultados de uma consulta, páginas de uma API
[Channel] (quente)
uma fila entre corrotinas: cada valor é recebido por um único consumidor (produtor/consumidores, balanceamento de carga)
[SharedFlow] (quente)
uma transmissão: cada valor é recebido por todos os assinantes presentes (eventos, mensagens)
[StateFlow] (quente)
Um estado observável: um valor atual e suas mudanças

9.11. Cache, retorno à thread correta e conclusão manual da operação

9.11.1. Um cache para operações assíncronas

Um [Deferred], como um [CompletableFuture], é um objeto: cada chamada a uma função que retorna um deles aloca pelo menos um objeto no heap, que o coletor de lixo precisará recuperar. Isso é desprezível para uma E/S que dura milissegundos. As funções de suspensão, de fato, têm uma vantagem sobre os objetos [CompletableFuture]: uma função de suspensão que já tem seu resultado o devolve diretamente, sem suspender a corrotina, sem trocar de thread e sem criar um objeto [Deferred]; da mesma forma, [await()] em um [Deferred] que já foi concluído retorna seu valor sem suspender. É o que outras linguagens obtêm com um tipo “leve” (a estrutura [ValueTask] do C#, por exemplo).

Quando se quer que várias requisições concorrentes pelo mesmo valor compartilhem a mesma operação em andamento, a melhor prática continua sendo armazenar em cache os próprios objetos [Deferred] em si: um valor já conhecido é retornado por um [Deferred] concluído, e um valor que está sendo calculado é retornado pelo [Deferred] desse cálculo. O programa [Async27.kt] aplica isso ao serviço de taxas de câmbio do programa Java:

// um cache de Deferreds: uma operação assíncrona que, na maioria das vezes, já tem o resultado
package async27

import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.CoroutineStart
import kotlinx.coroutines.Deferred
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.async
import kotlinx.coroutines.cancel
import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking
import java.math.BigDecimal
import java.text.NumberFormat
import java.util.concurrent.ConcurrentHashMap
import java.util.concurrent.atomic.AtomicInteger
import kotlin.time.measureTimedValue

fun main() = runBlocking<Unit> {
    RateService().use { service ->
        // 1 - leituras sucessivas: apenas a primeira leitura de uma moeda consulta o servidor
        for (code in listOf("EUR", "USD", "EUR", "EUR", "USD", "GBP", "EUR")) {
            val (rate, duration) = measureTimedValue { service.readRate(code).await() }
            println("%s : %6s read in %3d ms".format(code, format(rate), duration.inWholeMilliseconds))
        }
        println("1 - server accesses: ${service.nbServerAccesses}, reads: ${service.nbReads}")

        // 2 - três leituras simultâneas da mesma moeda: elas compartilham a mesma operação
        val reads = List(3) { service.readRate("CHF") }
        println("2 - same object: ${reads[0] === reads[2]}, rate: ${format(reads[0].await())}" +
                ", server accesses: ${service.nbServerAccesses}, reads: ${service.nbReads}")

        // 3 - uma operação que falhou não é mantida no cache
        try {
            service.readRate("XYZ").await()
        } catch (e: IllegalArgumentException) {
            println("3 - ${e.message}, currencies in cache: ${service.currenciesInCache()}")
        }
    }
}

class RateService : AutoCloseable {
    // o escopo das leituras: ele pertence ao serviço, e a falha de uma leitura não cancela as outras
    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)

    // o cache contém os próprios Deferreds, terminados ou em andamento
    private val cache = ConcurrentHashMap<String, Deferred<BigDecimal>>()
    private val serverAccesses = AtomicInteger()
    private val reads = AtomicInteger()
    val nbServerAccesses get() = serverAccesses.get()
    val nbReads get() = reads.get()

    fun readRate(code: String): Deferred<BigDecimal> {
        reads.incrementAndGet()
        // se a moeda estiver no cache, o Deferred existente é devolvido: nenhum objeto é criado
        return cache.computeIfAbsent(code, ::readServerRate).also { it.start() }
    }

    // uma leitura lazy: ela só começa com start(), depois de armazenada no cache
    private fun readServerRate(code: String): Deferred<BigDecimal> =
        scope.async(start = CoroutineStart.LAZY) {
            serverAccesses.incrementAndGet()
            try {
                // simula a consulta a um servidor remoto (300 ms)
                delay(300)
                when (code) {
                    "EUR" -> BigDecimal.ONE
                    "USD" -> BigDecimal("1.17")
                    "GBP" -> BigDecimal("0.87")
                    "CHF" -> BigDecimal("0.94")
                    else -> throw IllegalArgumentException("unknown currency: $code")
                }
            } catch (e: Exception) {
                // em caso de falha, a leitura é removida do cache: uma leitura posterior será tentada novamente
                cache.remove(code)
                throw e
            }
        }

    fun currenciesInCache() = cache.keys.sorted()

    // fechar o serviço cancela as leituras em andamento
    override fun close() = scope.cancel()
}

// um número real no formato do idioma da máquina, sem casas decimais inúteis
fun format(value: BigDecimal): String = NumberFormat.getInstance().format(value)

Resultados:

> gradlew -q run -Pmain=async27.Async27Kt
EUR :      1 read in 391 ms
USD :   1.17 read in 301 ms
EUR :      1 read in   0 ms
EUR :      1 read in   0 ms
USD :   1.17 read in   0 ms
GBP :   0.87 read in 300 ms
EUR :      1 read in   0 ms
1 - server accesses: 3, reads: 7
2 - same object: true, rate: 0.94, server accesses: 4, reads: 10
3 - unknown currency: XYZ, currencies in cache: [CHF, EUR, GBP, USD]

Comentários:

  • Linha 44: o serviço lança corrotinas (as leituras) que devem poder sobreviver à corrotina que as solicitou: uma leitura solicitada por um chamador é compartilhada com os chamadores seguintes. Portanto, elas não podem pertencer ao escopo de um chamador; pertencem a um escopo próprio do serviço — um escopo de componente (programa [Async16.kt]). Seu [SupervisorJob] garante que a falha de uma leitura não cancele as outras; seu dispatcher é [Dispatchers.Default];
  • linha 83: o serviço implementa [AutoCloseable]; seu fechamento cancela o escopo e, portanto, todas as leituras em andamento. O programa principal usa o serviço dentro de um bloco [use] (linha 20): nenhuma corrotina sobrevive a ele;
  • linha 47: o cache associa cada código de moeda ao [Deferred] de sua taxa de câmbio, concluído ou ainda em andamento. Trata-se de um [ConcurrentHashMap] (Capítulo 8), pois ele pode ser usado por várias threads ao mesmo tempo (a thread principal, as threads do dispatcher [Default] que executam as leituras);
  • linhas 50–51: os contadores são objetos [AtomicInteger] privados, expostos externamente por duas propriedades somente leitura cujo acessor [get()] lê o valor atual (Capítulo 4);
  • linhas 53–56: [computeIfAbsent(key, function)] retorna o valor associado à chave, se existir; caso contrário, chama a função (aqui, a referência [::readServerRate]), armazena seu resultado no dicionário e o retorna. Em um [ConcurrentHashMap], essa operação é atômica: duas corrotinas que solicitam ao mesmo tempo uma moeda ausente disparam um único acesso ao servidor. [readRate] não é uma função de suspensão: ela retorna um [Deferred], que o chamador espera com [await()] quando quiser;
  • linhas 60–61: a operação de leitura é iniciada por [async] com a opção [start = CoroutineStart.LAZY]: a corrotina é criada, mas não começa; ela começará na primeira chamada a [start()] ou [await()]. [readRate] a inicia por meio de [.also { it.start() }], depois que [computeIfAbsent] a armazenou no cache ([start()] não tem efeito sobre uma corrotina que já começou ou terminou). Essa precaução garante que a operação de leitura não possa terminar — nem tentar remover a si mesma do cache — antes de ter sido armazenada nele; ela também impede que qualquer coisa seja executada dentro da função [computeIfAbsent], que deve ser curta porque é executada enquanto o dicionário está bloqueado para aquela chave;
  • linhas 64–71: a consulta simulada ao servidor (300 ms). A expressão [when] aplicada a uma string retorna a taxa de câmbio ou lança uma exceção para uma moeda desconhecida;
  • linhas 73–76: em caso de falha, a operação é removida do cache para que uma solicitação posterior da mesma moeda consulte o servidor novamente, em vez de retornar indefinidamente a mesma falha. A remoção é feita na corrotina antes de ela terminar: o chamador que recebe a exceção por meio de [await()] encontra um cache já atualizado (o programa Java obtinha a mesma garantia com [whenComplete]). A exceção é relançada; se for uma [CancellationException] (encerramento do serviço), ela também é relançada, e uma leitura cancelada tampouco permanece no cache;
  • linhas 21–26: para o chamador, uma leitura é uma operação assíncrona como qualquer outra: ele a espera com [await()]. A função [measureTimedValue] retorna ao mesmo tempo o resultado do bloco e sua duração, recuperados por meio de uma atribuição com desestruturação. Os resultados mostram os 3 acessos ao servidor (300 ms cada; um pouco mais no primeiro, durante o qual a JVM carrega as classes necessárias) e as 4 respostas imediatas do cache;
  • linhas 28–31: três solicitações simultâneas da taxa de câmbio do franco suíço obtêm o mesmo objeto (o operador [===] compara as referências) e resultam em um único acesso ao servidor (linha 10 dos resultados);
  • linhas 33–37: [await()] relança a exceção da leitura, que é capturada por um [catch] padrão (o programa Java recebia uma [CompletionException] que envolvia a exceção original); a moeda desconhecida já não está no cache (linha 11). A função [currenciesInCache] retorna as chaves do dicionário ordenadas ([sorted()]).

O cache de [Deferred] é adequado quando cada valor é calculado independentemente dos outros. Em contrapartida, quando apenas uma corrotina por vez pode executar uma seção de código com suspensão, usa-se um lock de corrotinas — especificamente, a classe [Mutex] do pacote [kotlinx.coroutines.sync]: [mutex.withLock { … }] executa o bloco de forma mutuamente exclusiva, e uma corrotina que encontra o lock ocupado fica suspensa sem bloquear sua thread. Um cache simples seria implementado com [suspend fun readRate(code: String) = mutex.withLock { cache.getOrPut(code) { readServerRate(code) } }], junto com um [MutableMap] padrão, que o lock protege. É mais simples que o cache de [Deferred], mas faz todas as leituras — mesmo as de outra moeda — esperarem durante cada acesso ao servidor. Não se devem usar os locks do Capítulo 8 ([synchronized], [ReentrantLock]) em torno de uma chamada de suspensão: eles pertencem a uma thread, ao passo que uma corrotina pode ser retomada em uma thread diferente daquela em que adquiriu o lock ([synchronized] em torno de uma chamada de suspensão é, de fato, rejeitado pelo compilador).

9.11.2. Voltando à thread da interface gráfica

O programa [Async09.kt] demonstrou que é o dispatcher que decide qual thread executa uma corrotina — e, portanto, qual thread executa o restante do código após uma suspensão. Em uma aplicação gráfica, isso importa: um componente gráfico só pode ser manipulado pela thread da interface. Enquanto o Java exige que o programa retome a execução nessa thread por conta própria ([SwingUtilities.invokeLater] com Swing, [Platform.runLater] com JavaFX), o kotlinx.coroutines oferece um dispatcher dedicado, [Dispatchers.Main], cujas corrotinas são executadas na thread da interface:

  • ele é fornecido por um módulo complementar específico da biblioteca gráfica: [kotlinx-coroutines-android] (Android), [kotlinx-coroutines-javafx] (JavaFX), [kotlinx-coroutines-swing] (Swing); sem esse módulo, usá-lo lançará uma exceção:
java.lang.IllegalStateException: Module with the Main dispatcher is missing. Add dependency providing the Main dispatcher, e.g. 'kotlinx-coroutines-android' and ensure it has the same version as 'kotlinx-coroutines-core'
  • O código da interface é executado em corrotinas lançadas em [Dispatchers.Main] e passa para outro dispatcher durante uma tarefa demorada: [val page = withContext(Dispatchers.IO) { download(address) }], depois [textArea.text = page]. Após [withContext], a corrotina voltou automaticamente à thread da interface: não há nada a solicitar. É o que o [await] do C# faz em uma aplicação gráfica, retomando o método na thread da interface;
  • No Android, os componentes fornecem seu próprio escopo, vinculado ao seu ciclo de vida ([lifecycleScope] para uma activity, [viewModelScope] para um view model), cujo dispatcher é [Dispatchers.Main]: quando a tela é destruída, o escopo é cancelado e, com ele, todas as corrotinas que ele havia lançado. Essa é a concorrência estruturada aplicada às interfaces;
  • o coletor de um fluxo é executado no dispatcher da corrotina que coleta (a thread da interface), enquanto [flowOn] faz os valores serem gerados em outro lugar (programa [Async24.kt]). Um [StateFlow] coletado em [Dispatchers.Main] é a forma padrão de exibir um estado que muda.

A regra continua a mesma do curso de Java: a thread da interface nunca deve bloquear ([runBlocking], [Thread.sleep], [join()] de um [CompletableFuture], E/S bloqueante), sob pena de a janela congelar. Mas ela pode suspender o quanto quiser: uma corrotina de [Dispatchers.Main] que está esperando um [await()] ou um [delay] devolve a thread à biblioteca gráfica, que continua a processar os eventos.

9.11.3. Concluindo uma operação manualmente: CompletableDeferred

Às vezes pode ser necessário usar uma API que sinaliza seus eventos por meio de listeners (Capítulo 7), enquanto o restante do código é escrito com corrotinas. O Kotlinx.coroutines oferece duas ferramentas para isso:

  • A classe [CompletableDeferred<T>], o equivalente de [CompletableFuture], que você mesmo conclui: trata-se de um [Deferred<T>] “pendente”, que você entrega imediatamente e conclui depois, no momento oportuno, com [complete(value)] (sucesso), [completeExceptionally(exception)] (falha) ou [cancel()] (cancelamento). Como em [CompletableFuture], quem o concluir primeiro vence: as chamadas seguintes não têm efeito ([complete] e [completeExceptionally] passam então a retornar [false]);
  • a função [suspendCancellableCoroutine], já usada nos programas [Async02.kt] e [Async21.kt], que transforma o evento esperado em uma função de suspensão cancelável.

O programa [Async28.kt] reimplementa o programa Java que esperava um termômetro — que notifica seus listeners a cada medição — atingir certa temperatura:

// concluindo uma operação por conta própria: CompletableDeferred e depois suspendCancellableCoroutine,
// para transformar uma API baseada em listeners em uma operação assíncrona
package async28

import kotlinx.coroutines.CompletableDeferred
import kotlinx.coroutines.Deferred
import kotlinx.coroutines.TimeoutCancellationException
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.suspendCancellableCoroutine
import kotlinx.coroutines.withTimeout
import kotlinx.coroutines.withTimeoutOrNull
import java.text.NumberFormat
import java.util.concurrent.CopyOnWriteArrayList
import java.util.concurrent.Executors
import java.util.concurrent.TimeUnit
import kotlin.coroutines.resume

val start = System.nanoTime()

fun main() = runBlocking {
    val thermometer = Thermometer()
    thermometer.start()

    // 1 - esperamos a primeira medição maior ou igual a 21 °C
    val measurement = awaitTemperature(thermometer, 21.0).await()
    display("1 - temperature reached: ${format(measurement)} °C, listeners: ${thermometer.nbListeners}")

    // 2 - a mesma espera, limitada a 600 ms: é a espera que é abandonada, não a operação
    val waiting = awaitTemperature(thermometer, 30.0)
    val measurement2 = withTimeoutOrNull(600) { waiting.await() }
    display("2 - result: $measurement2, listeners: ${thermometer.nbListeners}")
    // a operação deve ser cancelada manualmente para remover o listener
    waiting.cancel()
    display("2 - after cancel(): listeners: ${thermometer.nbListeners}")

    // 3 - uma função suspensa cancelável: o timeout cancela a própria operação
    try {
        withTimeout(600) { temperatureReached(thermometer, 30.0) }
    } catch (e: TimeoutCancellationException) {
        display("3 - 30 °C not reached in 600 ms, listeners: ${thermometer.nbListeners}")
    }
    thermometer.stop()
}

// transforma as notificações do termômetro em um Deferred que concluímos nós mesmos
fun awaitTemperature(thermometer: Thermometer, threshold: Double): Deferred<Double> {
    val result = CompletableDeferred<Double>()
    // o listener conclui o Deferred quando o limite é atingido
    val listener = { temperature: Double ->
        if (temperature >= threshold) result.complete(temperature)
    }
    thermometer.addListener(listener)
    // qualquer que seja a forma como termina (limite, falha, cancelamento), o listener é removido
    result.invokeOnCompletion { thermometer.removeListener(listener) }
    // o Deferred é devolvido imediatamente; ele será concluído mais tarde
    return result
}

// a mesma coisa como uma função suspensa cancelável
suspend fun temperatureReached(thermometer: Thermometer, threshold: Double): Double =
    suspendCancellableCoroutine { continuation ->
        lateinit var listener: (Double) -> Unit
        listener = { temperature ->
            if (temperature >= threshold && continuation.isActive) {
                thermometer.removeListener(listener)
                continuation.resume(temperature)
            }
        }
        thermometer.addListener(listener)
        // se a corrotina for cancelada durante a espera, o listener é removido
        continuation.invokeOnCancellation { thermometer.removeListener(listener) }
    }

// um termômetro que notifica seus listeners a cada 200 ms (uma API "à moda antiga")
class Thermometer {
    private val listeners = CopyOnWriteArrayList<(Double) -> Unit>()
    private val timer = Executors.newSingleThreadScheduledExecutor()
    private var temperature = 19.0
    val nbListeners get() = listeners.size

    fun addListener(listener: (Double) -> Unit) = listeners.add(listener)

    fun removeListener(listener: (Double) -> Unit) = listeners.remove(listener)

    fun start() {
        timer.scheduleAtFixedRate({
            temperature += 0.5
            println("          measurement: ${format(temperature)} °C")
            listeners.forEach { listener -> listener(temperature) }
        }, 200, 200, TimeUnit.MILLISECONDS)
    }

    fun stop() = timer.shutdown()
}

// um número real no formato do idioma da máquina, sem casas decimais inúteis
fun format(value: Double): String = NumberFormat.getInstance().format(value)

// exibição com o tempo decorrido desde o início
fun display(message: String) =
    println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

Resultados:

> gradlew -q run -Pmain=async28.Async28Kt
          measurement: 19.5 °C
          measurement: 20 °C
          measurement: 20.5 °C
          measurement: 21 °C
  961 ms : 1 - temperature reached: 21 °C, listeners: 0
          measurement: 21.5 °C
          measurement: 22 °C
          measurement: 22.5 °C
 1571 ms : 2 - result: null, listeners: 1
 1578 ms : 2 - after cancel(): listeners: 0
          measurement: 23 °C
          measurement: 23.5 °C
          measurement: 24 °C
 2181 ms : 3 - 30 °C not reached in 600 ms, listeners: 0

Comentários:

  • Linhas 75–93: o termômetro, uma classe “à moda antiga”: um [ScheduledExecutorService] aumenta a temperatura em 0,5 °C a cada 200 ms e a transmite a seus listeners, do tipo [(Double) -> Unit]. A lista de listeners é uma [CopyOnWriteArrayList], uma lista que pode ser modificada por uma thread (adição ou remoção de um listener) enquanto outra thread a percorre. A propriedade [nbListeners] permitirá verificar se os listeners foram removidos corretamente;
  • Linhas 46–56: a função que converte notificações em [Deferred]. Ela cria um [CompletableDeferred<Double>] temporário, registra um listener no termômetro e retorna imediatamente o [CompletableDeferred] (tratado como um [Deferred<Double>]: o chamador não pode concluí-lo por conta própria), que ainda não está concluído;
  • linhas 49–50: a cada medição, o listener testa o limite. Quando ele é atingido, conclui o [CompletableDeferred] com a temperatura como resultado. As medições seguintes ainda chamariam [complete], sem efeito, até que o listener seja removido;
  • linha 54: qualquer que seja a forma como o [Deferred] termine (limite atingido, falha, cancelamento), a ação registrada por [invokeOnCompletion] remove o listener: é o [whenComplete] do programa Java. Sem isso, um listener cujo limite nunca fosse atingido permaneceria registrado indefinidamente;
  • linhas 24–26: para o chamador, esperar por uma temperatura é uma operação assíncrona como qualquer outra: ele a espera com [await()]. Uma vez atingido o limite, o listener foi removido (linha 6 dos resultados: 0 listeners);
  • linhas 28–34: uma diferença significativa em relação ao programa Java, em que [orTimeout] concluía [CompletableFuture] por conta própria. Aqui, [withTimeoutOrNull] cancela o bloco de espera ([await()]), e não o [Deferred] esperado: após 600 ms, a espera é abandonada ([null]), mas a operação continua, e seu listener ainda está registrado (linha 10 dos resultados: 1 listener). Um [CompletableDeferred] não é filho de nenhuma corrotina: a concorrência estruturada não se aplica a ele, e cabe ao seu criador cancelá-lo com [cancel()], o que remove o listener (linha 11);
  • Linhas 60–71: a mesma espera, escrita como uma função de suspensão com [suspendCancellableCoroutine]. O listener retoma a corrotina com a temperatura ([resume]) depois de se remover. Como precisa se referir a si mesmo, ele é declarado com [lateinit var] antes de ser inicializado: uma lambda não pode referenciar a variável à qual está sendo atribuída. O teste [continuation.isActive] impede que a continuação seja retomada duas vezes (o que dispararia uma [IllegalStateException]). [invokeOnCancellation] registra a ação a ser realizada se a corrotina for cancelada enquanto espera: a remoção do listener;
  • Linhas 36–40: desta vez, [withTimeout] cancela a corrotina suspensa em [temperatureReached]: a ação [invokeOnCancellation] remove o listener, e não há mais nada a fazer (linha 15: 0 listeners).

Preferimos, portanto, a segunda forma: uma função de suspensão construída com [suspendCancellableCoroutine] participa do cancelamento e da concorrência estruturada, ao passo que um [CompletableDeferred] é um objeto independente que seu criador deve se lembrar de concluir em todos os casos. O [CompletableDeferred] continua útil para um valor esperado por várias corrotinas (um sinal de partida, por exemplo) ou para um resultado fornecido por uma corrotina a outra. Uma precaução, a mesma do Java: o listener é executado pela thread do termômetro, no meio das notificações a seus listeners; ele deve ser mantido curto. É o caso aqui: [complete] e [resume] apenas delegam ao seu dispatcher a retomada da corrotina (a thread principal, a de [runBlocking]).

9.12. Paralelismo limitado

9.12.1. Semaphore e limitedParallelism

[awaitAll] e uma corrotina por operação lançam todas as operações simultaneamente. Isso nem sempre é desejável: para baixar 10.000 páginas web, você não quer abrir 10.000 conexões simultâneas com o mesmo servidor. Como as threads virtuais, as corrotinas não são mantidas em pool (são tão baratas que se lança uma por tarefa): o que se limita é o acesso ao recurso escasso. O Kotlinx.coroutines oferece duas ferramentas para isso:

  • um semáforo de corrotinas, a classe [Semaphore] do pacote [kotlinx.coroutines.sync] (não confundir com a de [java.util.concurrent], apresentada no Capítulo 8): suas permissões representam o número de operações simultâneas permitidas; uma corrotina que espera por uma permissão fica suspensa, sem bloquear nenhuma thread;
  • uma visão limitada de um dispatcher, [dispatcher.limitedParallelism(n)], registrada com o programa [Async09.kt]: um dispatcher que usa as threads do dispatcher original, mas nunca mais de [n] ao mesmo tempo.

O programa [Async29.kt] retoma o programa Java que baixava nove páginas — no máximo três por vez — e depois compara as duas ferramentas:

// processamento de uma coleção com um número limitado de operações simultâneas:
// o Semaphore do kotlinx.coroutines e depois limitedParallelism
package async29

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.sync.Semaphore
import kotlinx.coroutines.sync.withPermit
import java.util.concurrent.atomic.AtomicInteger
import kotlin.time.measureTime

val pages = (1..9).map { "page$it.html" }
val inProgress = AtomicInteger()
val maximum = AtomicInteger()
var start = System.nanoTime()

fun main() = runBlocking {
    // 1 - no máximo 3 downloads ao mesmo tempo: um semáforo de corrotinas com 3 permissões
    start = System.nanoTime()
    val permits = Semaphore(3)
    coroutineScope {
        // uma corrotina por página: elas são baratas, podem ser lançadas tantas quantas forem as páginas
        for (page in pages) {
            launch {
                // a corrotina espera por uma permissão (ela é suspensa, sem bloquear uma thread)
                permits.withPermit { download(page, trace = true) }
            }
        }
    }
    display("1 - the ${pages.size} pages are downloaded")

    // 2 - downloads bloqueantes em uma view do dispatcher IO limitada a 3 threads
    val threeThreads = Dispatchers.IO.limitedParallelism(3)
    maximum.set(0)
    val duration2 = measureTime {
        coroutineScope {
            for (page in pages) launch(threeThreads) { downloadBlocking(page) }
        }
    }
    println("2 - limitedParallelism(3), blocking: ${duration2.inWholeMilliseconds} ms, " +
            "at most ${maximum.get()} in progress")

    // 3 - a mesma view limita as threads, não as corrotinas suspensas: aqui, nenhum limite
    maximum.set(0)
    val duration3 = measureTime {
        coroutineScope {
            for (page in pages) launch(threeThreads) { download(page) }
        }
    }
    println("3 - limitedParallelism(3), suspended: ${duration3.inWholeMilliseconds} ms, " +
            "at most ${maximum.get()} in progress")
}

// o download simulado de uma página, por uma função suspensa
suspend fun download(page: String, trace: Boolean = false) {
    // contador compartilhado pelas operações simultâneas: ele é modificado atomicamente
    val n = inProgress.incrementAndGet()
    maximum.accumulateAndGet(n, ::maxOf)
    if (trace) display("start of $page ($n in progress)")
    delay(1000)
    inProgress.decrementAndGet()
    if (trace) display("end of $page")
}

// o mesmo download, por uma função bloqueante
fun downloadBlocking(page: String) {
    val n = inProgress.incrementAndGet()
    maximum.accumulateAndGet(n, ::maxOf)
    Thread.sleep(1000)
    inProgress.decrementAndGet()
}

// exibição com o tempo decorrido desde [start]
fun display(message: String) =
    println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

Resultados:

> gradlew -q run -Pmain=async29.Async29Kt
   39 ms : start of page1.html (1 in progress)
   76 ms : start of page2.html (2 in progress)
   76 ms : start of page3.html (3 in progress)
 1118 ms : end of page1.html
 1122 ms : end of page2.html
 1122 ms : end of page3.html
 1122 ms : start of page4.html (1 in progress)
 1122 ms : start of page5.html (2 in progress)
 1122 ms : start of page6.html (3 in progress)
 2125 ms : end of page4.html
 2126 ms : end of page5.html
 2127 ms : end of page6.html
 2127 ms : start of page7.html (1 in progress)
 2127 ms : start of page8.html (2 in progress)
 2128 ms : start of page9.html (3 in progress)
 3135 ms : end of page7.html
 3142 ms : end of page8.html
 3143 ms : end of page9.html
 3151 ms : 1 - the 9 pages are downloaded
2 - limitedParallelism(3), blocking: 3025 ms, at most 3 in progress
3 - limitedParallelism(3), suspended: 1006 ms, at most 9 in progress

Comentários:

  • linha 23: um semáforo de corrotinas com 3 permissões;
  • linhas 24–33: uma corrotina por página. O bloco [coroutineScope] espera o término das nove corrotinas, de forma semelhante ao método [close()] do executor do programa Java;
  • linha 29: cada corrotina espera por uma permissão, baixa sua página e depois devolve a permissão. A função [withPermit] faz tudo isso: ela obtém uma permissão ([acquire()], uma função de suspensão), executa o bloco e devolve a permissão ([release()]) em um [finally], de modo que ela seja devolvida mesmo que o bloco falhe ou a corrotina seja cancelada. O programa Java precisava escrever ele mesmo o [try / finally] e tratar a [InterruptedException] de [acquire];
  • linhas 58–65: o download simulado de uma página, uma função de suspensão que espera um segundo. O contador [inProgress], compartilhado pelas corrotinas, é um [AtomicInteger]: as corrotinas lançadas por [runBlocking] são executadas aqui em uma única thread, mas as das Partes 2 e 3 são executadas em várias threads. O contador [maximum] registra o maior número de downloads simultâneos: [accumulateAndGet(n, ::maxOf)] o substitui atomicamente pelo maior entre seu próprio valor e o de [n] (a função da biblioteca padrão [maxOf], passada por referência);
  • Os resultados da Parte 1 mostram três ondas de três páginas: assim que uma página termina, outra começa, e o número de downloads ativos nunca passa de 3. O processo inteiro leva 3 segundos em vez de 9. Essas nove corrotinas foram executadas por uma única thread, a de [runBlocking];
  • Linhas 35–43: [Dispatchers.IO.limitedParallelism(3)] é uma visão do dispatcher [IO] limitada a 3 threads. As nove corrotinas são lançadas nessa visão e executam um download bloqueante ([Thread.sleep]): apenas três podem executar por vez; as outras esperam que uma thread fique disponível. O processo inteiro leva 3 segundos, com no máximo 3 downloads em andamento (linha 21 dos resultados). Essa é a ferramenta certa para limitar uma tarefa bloqueante (uma biblioteca JDBC, arquivos) ou um cálculo: uma visão de [Dispatchers.IO] gerada por [limitedParallelism] pode inclusive exceder o limite de 64 threads de [Dispatchers.IO], o que permite atribuir a cada recurso bloqueante sua própria cota de threads (por exemplo, tantas quanto as conexões de um pool de conexões de banco de dados);
  • linhas 46–53: a mesma visão, com o download em pausa ([delay]). Desta vez, os nove downloads ocorrem simultaneamente, e o processo inteiro leva um segundo (linha 22). [limitedParallelism] limita o número de corrotinas em execução ao mesmo tempo — isto é, o número de threads ocupadas; uma corrotina suspensa não ocupa uma thread e não é contada. Para limitar o número de operações em andamento (conexões, consultas), é preciso, portanto, usar o semáforo.

Ponto principal: limitedParallelism limita threads; o semáforo limita operações.

9.12.2. Produtores/consumidores: workers lendo um canal

O capítulo anterior apresentou o modelo produtor/consumidor com uma [BlockingQueue], e o curso de Java o implementou com threads virtuais. Com corrotinas, a ferramenta é o canal: [send] substitui [put], o laço [for] sobre o canal substitui as sucessivas chamadas a [take] e [trySend] substitui [offer] (uma tentativa não bloqueante). Várias corrotinas que leem o mesmo canal dividem seus valores: essa é outra forma de limitar o paralelismo, lançando um número fixo de “workers” que processam as tarefas uma após a outra. O programa [Async30.kt] tem pedidos — gerados a cada 50 ms — processados por dois consumidores, cada um dos quais leva 400 ms para processar um pedido:

// produtor / consumidores: corrotinas "worker" que compartilham os pedidos de um canal
package async30

import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.channels.Channel
import kotlinx.coroutines.channels.ReceiveChannel
import kotlinx.coroutines.channels.SendChannel
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

val start = System.nanoTime()

fun main() = runBlocking {
    // um canal limitado: ele contém no máximo 2 pedidos aguardando processamento
    val orders = Channel<Int>(capacity = 2)
    coroutineScope {
        // o produtor e dois consumidores trabalham ao mesmo tempo
        launch { produceOrders(orders, 8) }
        launchWorkers(orders, "C1", "C2")
    }
    display("all the orders have been processed")
}

// o produtor: um pedido a cada 50 ms
suspend fun produceOrders(orders: SendChannel<Int>, nbOrders: Int) {
    for (i in 1..nbOrders) {
        delay(50)
        // trySend coloca o pedido imediatamente se houver espaço no canal
        if (orders.trySend(i).isSuccess) {
            display("P  : order $i put")
        } else {
            // canal cheio: send suspende o produtor até que uma vaga fique livre
            display("P  : channel full, order $i waits")
            orders.send(i)
            display("P  : order $i put")
        }
    }
    // nada mais será produzido: o canal é fechado
    orders.close()
    display("P  : end of production")
}

// lança um worker por nome: cada um recebe os pedidos do canal até que ele seja fechado
fun CoroutineScope.launchWorkers(orders: ReceiveChannel<Int>, vararg names: String) {
    for (name in names) {
        launch {
            // processar um pedido leva 400 ms
            for (order in orders) {
                display("$name : processing order $order")
                delay(400)
            }
            display("$name : no more orders")
        }
    }
}

// exibição com o tempo decorrido desde o início
fun display(message: String) =
    println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

Resultados:

> gradlew -q run -Pmain=async30.Async30Kt
  195 ms : P  : order 1 put
  225 ms : C1 : processing order 1
  271 ms : P  : order 2 put
  271 ms : C2 : processing order 2
  322 ms : P  : order 3 put
  373 ms : P  : order 4 put
  423 ms : P  : channel full, order 5 waits
  625 ms : C1 : processing order 3
  626 ms : P  : order 5 put
  672 ms : C2 : processing order 4
  676 ms : P  : order 6 put
  727 ms : P  : channel full, order 7 waits
 1026 ms : C1 : processing order 5
 1026 ms : P  : order 7 put
 1073 ms : C2 : processing order 6
 1077 ms : P  : order 8 put
 1079 ms : P  : end of production
 1427 ms : C1 : processing order 7
 1473 ms : C2 : processing order 8
 1833 ms : C1 : no more orders
 1874 ms : C2 : no more orders
 1875 ms : all the orders have been processed

Comentários:

  • linha 17: um canal com capacidade 2: ele contém no máximo 2 pedidos pendentes;
  • linhas 18–21: o produtor e os dois consumidores são três corrotinas filhas do bloco [coroutineScope], que espera o término das três;
  • linhas 27–42: o produtor recebe o canal como um [SendChannel<Int>], a parte “enviar” do canal: ele só pode enviar. Ele tenta depositar cada pedido com [trySend], que nunca suspende e retorna um [ChannelResult] cuja propriedade [isSuccess] indica se o valor foi depositado. Se o canal está cheio, ele sinaliza isso e espera por espaço com [send]: o produtor é freado para acompanhar o ritmo dos consumidores (linhas 8–10 dos resultados). Esse é o benefício de um canal limitado: um produtor rápido demais não consegue encher a memória;
  • linha 41: a produção terminou; o produtor fecha o canal. O programa Java precisava colocar um valor específico — o marcador de fim — que cada consumidor reconhecia e devolvia à fila para o seguinte; um canal, em contrapartida, sabe quando está fechado. Fechar o canal não exige espaço no canal: o fim da produção é sinalizado assim que o último pedido é colocado (linha 18), ao passo que, em Java, a colocação do marcador de fim precisava esperar por uma vaga livre;
  • linhas 46–54: os consumidores são lançados por uma função de extensão de [CoroutineScope] (programa [Async25.kt]), cujo parâmetro [vararg names] (Capítulo 3) aceita qualquer número de nomes. Cada worker percorre o canal com um laço [for], que termina quando o canal está fechado e vazio. Um pedido é entregue a apenas um worker: os pedidos são distribuídos entre C1 e C2 conforme a disponibilidade deles;
  • duas linhas exibidas quase ao mesmo tempo podem aparecer em uma ordem que varia de uma execução para outra.

Para processar uma lista conhecida de antemão com [n] workers, enviamos os elementos a um canal, o fechamos e lançamos [n] corrotinas para lê-lo: ao contrário de um semáforo, que lança uma corrotina por elemento, essa abordagem lança apenas [n] corrotinas, o que faz diferença quando se lida com milhões de elementos.

9.13. Tempo

Quando se trata de tempo em corrotinas, a primeira função a considerar é [delay]: uma espera que não bloqueia uma thread, é cancelável e aceita um número de milissegundos ou uma duração ([Duration]: [delay(500.milliseconds)]). As funções [withTimeout] e [withTimeoutOrNull] (programa [Async19.kt]) limitam a duração de um bloco. Com essas duas ferramentas, escrever um temporizador é simples: uma corrotina que faz um laço esperando entre duas ações e que é interrompida por cancelamento. O curso de Java usava um [ScheduledExecutorService] para isso; o programa [Async31.kt] implementa os dois tipos de temporizadores periódicos com corrotinas e depois reutiliza a classe [Reception] do programa Java, que depende da hora:

// tempo: timers escritos com delay e um relógio injetado (Clock)
package async31

import kotlinx.coroutines.cancelAndJoin
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import java.time.Clock
import java.time.Instant
import java.time.LocalDateTime
import java.time.ZoneOffset
import java.time.format.DateTimeFormatter
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.TimeSource

fun main() = runBlocking {
    // 1 - uma ação a cada 500 ms: um atraso fixo entre o fim de uma ação e o início da próxima
    var start = TimeSource.Monotonic.markNow()
    var nbTicks = 0
    val ticks = launch {
        while (true) {
            delay(500)
            nbTicks++
            println("%6d ms : tick no. %d".format(start.elapsedNow().inWholeMilliseconds, nbTicks))
            // a própria ação dura 100 ms
            delay(100)
        }
    }
    // uma única ação, em 2,2 segundos, que interrompe os ticks
    delay(2200)
    ticks.cancelAndJoin()
    println("%6d ms : 1 - timer stopped after %d ticks"
        .format(start.elapsedNow().inWholeMilliseconds, nbTicks))

    // 2 - em intervalos fixos: cada tick é alinhado ao instante programado, apesar da duração da ação
    start = TimeSource.Monotonic.markNow()
    nbTicks = 0
    val ticks2 = launch {
        var next = start + 500.milliseconds
        while (true) {
            // esperamos o tempo restante até o instante programado (nada se ele já passou)
            delay(-next.elapsedNow())
            nbTicks++
            println("%6d ms : tick no. %d".format(start.elapsedNow().inWholeMilliseconds, nbTicks))
            delay(100)
            next += 500.milliseconds
        }
    }
    delay(2200)
    ticks2.cancelAndJoin()
    println("%6d ms : 2 - timer stopped after %d ticks"
        .format(start.elapsedNow().inWholeMilliseconds, nbTicks))

    // 3 - Clock: uma classe que depende do tempo recebe seu relógio em vez de chamar LocalDateTime.now()
    val morning = Clock.fixed(Instant.parse("2026-10-03T09:30:00Z"), ZoneOffset.UTC)
    val evening = Clock.fixed(Instant.parse("2026-10-03T19:45:00Z"), ZoneOffset.UTC)
    println(Reception(morning).greet("Pierre"))
    println(Reception(evening).greet("Pierre"))
    println("${Reception(Clock.systemDefaultZone()).greet("Pierre")} (system clock)")
}

// uma classe que depende da hora atual
class Reception(private val clock: Clock) {
    fun greet(name: String): String {
        val now = LocalDateTime.now(clock)
        val greeting = if (now.hour < 18) "Hello" else "Good evening"
        val date = now.format(DateTimeFormatter.ofPattern("dd/MM/yyyy HH:mm"))
        return "[$date] $greeting $name"
    }
}

Resultados:

> gradlew -q run -Pmain=async31.Async31Kt
   511 ms : tick no. 1
  1145 ms : tick no. 2
  1746 ms : tick no. 3
  2229 ms : 1 - timer stopped after 3 ticks
   501 ms : tick no. 1
  1000 ms : tick no. 2
  1500 ms : tick no. 3
  2001 ms : tick no. 4
  2201 ms : 2 - timer stopped after 4 ticks
[03/10/2026 09:30] Hello Pierre
[03/10/2026 19:45] Good evening Pierre
[04/10/2026 13:03] Hello Pierre (system clock)

Comentários:

  • linha 18: para medir uma duração, usamos aqui o cronômetro monotônico da biblioteca padrão do Kotlin: [TimeSource.Monotonic.markNow()] retorna uma marca de tempo do instante atual, e [start.elapsedNow()] retorna a duração ([Duration]) decorrida desde então. Isso equivale a [System.nanoTime()], que usamos até agora, mas com durações tipadas;
  • linhas 20–31: uma ação a cada 500 ms, executada por uma corrotina que faz um laço indefinidamente ([while (true)]). O laço não oferece risco: cada [delay] é um ponto de cancelamento. Após 2,2 segundos, a corrotina principal a cancela e espera que ela termine ([cancelAndJoin()]). A variável [nbTicks] é uma simples variável local ([var]), modificada pela lambda de [launch]: o Kotlin permite que um closure modifique uma variável capturada (Capítulo 7), ao passo que o Java exigia um [AtomicInteger]; isso é seguro aqui porque todas as corrotinas são executadas na única thread de [runBlocking];
  • esse primeiro temporizador espera 500 ms depois de cada ação, que por sua vez dura 100 ms: o temporizador dispara a cada 600 ms (linhas 2–4 dos resultados; o primeiro intervalo é um pouco mais longo, enquanto as classes são carregadas). Esse é o comportamento do método [scheduleWithFixedDelay] de um [ScheduledExecutorService]: um atraso fixo entre o fim de uma execução e o início da seguinte;
  • linhas 38–46: o segundo temporizador é configurado para intervalos fixos: 500, 1.000, 1.500, 2.000 ms (linhas 6–9), independentemente da duração da ação. A variável [next] é a marca de tempo do próximo disparo ([start + 500.milliseconds]: uma marca de tempo mais uma duração resulta em uma marca de tempo). [next.elapsedNow()] é negativo enquanto esse instante está no futuro: [delay(-next.elapsedNow())] espera, portanto, o tempo restante (um atraso negativo ou zero não causa espera). Esse é o comportamento de [scheduleAtFixedRate]. O Kotlinx.coroutines não tem uma função de temporizador embutida que seja estável (a função [ticker] está marcada como obsoleta): o laço é a abordagem recomendada;
  • linhas 63–68: a classe [Reception] diz “Olá” ou “Boa noite” conforme a hora. Ela recebe seu relógio, um [java.time.Clock], em seu construtor, em vez de chamar [LocalDateTime.now()]: trata-se de uma dependência injetada, assim como a camada [dao] é injetada na camada [business] no Capítulo 6. [now.hour] é a chamada ao método Java [getHour()], tratado como uma propriedade;
  • linhas 55–59: [Clock.fixed(instant, zone)] retorna um relógio parado, que sempre devolve o mesmo horário: isso permite verificar o comportamento de [Reception] pela manhã e à noite sem precisar esperar até a noite. A última linha usa o relógio do sistema: o resultado, portanto, depende do horário de execução.

A título de lembrança, o [ScheduledExecutorService] do curso de Java ainda pode ser usado em Kotlin (o termômetro do programa [Async28.kt] usa um), mas suas tarefas são [Runnable]s executados por threads próprias, fora de qualquer corrotina. Em um programa baseado em corrotinas, é preferível usar uma corrotina e [delay], que terminam junto com seu escopo.

As funções de temporização das corrotinas têm outra vantagem, particularmente importante para testes: o módulo [kotlinx-coroutines-test] fornece uma função, [runTest], que executa as corrotinas usando tempo virtual: as funções [delay] não esperam de fato; o relógio virtual avança instantaneamente, e um teste que simula uma espera de um minuto leva apenas alguns milissegundos.

9.14. Corrotinas e threads virtuais

O curso de Java concluiu este capítulo com uma visão geral da concorrência estruturada, que trata um grupo de subtarefas como um bloco: elas são lançadas dentro de um escopo, o escopo espera que terminem e, se uma falha, as demais são abortadas. Em Kotlin, isso não é apenas uma visão geral: é a própria base das corrotinas, apresentada no início deste capítulo ([coroutineScope], [supervisorScope], programa [Async11.kt]) e usada em todos os exemplos desde então. É interessante comparar as duas linguagens, já que Java caminha na mesma direção.

9.14.1. StructuredTaskScope (Java) e coroutineScope (Kotlin)

A classe Java [StructuredTaskScope] implementa a concorrência estruturada usando threads virtuais. Ela está disponível desde o Java 21, mas ainda tem o status de “preview” no Java 25: sua API ainda pode mudar, e um programa que a utilize deve ser compilado e executado com a opção [--enable-preview]. Eis o código apresentado no curso de Java (arquivo [preview/StructuredConcurrency.txt] na pasta [09-async] do curso de Java):

// concorrência estruturada: API de preview no Java 25
// execução: java --enable-preview StructuredConcurrency.java
import java.util.concurrent.StructuredTaskScope.Joiner;
import java.util.concurrent.StructuredTaskScope.Subtask;

void main() throws InterruptedException {
    // 1 - duas subtarefas que devem ambas ter sucesso
    try (var scope = StructuredTaskScope.open()) {
        Subtask<Integer> angers = scope.fork(() -> readTemperature("Angers", 1000));
        Subtask<Integer> brest = scope.fork(() -> readTemperature("Brest", 500));
        // join espera o fim das subtarefas; se uma falhar, a outra é cancelada
        // e join lança uma exceção
        scope.join();
        IO.println("Angers: " + angers.get() + ", Brest: " + brest.get());
    }
    // 2 - a primeira resposta basta: as outras subtarefas são canceladas
    try (var scope = StructuredTaskScope.open(Joiner.<Integer>anySuccessfulResultOrThrow())) {
        scope.fork(() -> readTemperature("mirror-paris", 800));
        scope.fork(() -> readTemperature("mirror-lyon", 300));
        IO.println("first answer: " + scope.join());
    }
}

int readTemperature(String city, long duration) throws InterruptedException {
    Thread.sleep(duration);
    return 10 + city.length();
}

Resultados (execução com o JDK 25):

1
2
3
> java --enable-preview StructuredConcurrency.java
Angers: 16, Brest: 15
first answer: 21

[StructuredTaskScope.open()] abre um escopo declarado em um [try] com recurso; [fork] lança uma subtarefa em uma nova thread virtual; [join()] espera que todas as subtarefas terminem e, se alguma falhar, encerra as demais e lança uma exceção; um [Joiner] escolhe uma política diferente, como “a primeira subtarefa que for bem-sucedida retorna o resultado”. O programa [Async32.kt] faz o mesmo com corrotinas e, em seguida, demonstra que as corrotinas também podem lidar com código bloqueante executado por threads virtuais:

// a concorrência estruturada do Kotlin comparada com StructuredTaskScope (Java):
// as mesmas subtarefas, como corrotinas, e depois código bloqueante em threads virtuais
package async32

import kotlinx.coroutines.async
import kotlinx.coroutines.asCoroutineDispatcher
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.runInterruptible
import kotlinx.coroutines.selects.select
import java.util.concurrent.Executors
import kotlin.time.TimeSource

var start = TimeSource.Monotonic.markNow()

fun main() = runBlocking<Unit> {
    start = TimeSource.Monotonic.markNow()
    // 1 - duas subtarefas que devem ambas ter sucesso
    val (angers, brest) = coroutineScope {
        val angers = async { readTemperature("Angers", 1000) }
        val brest = async { readTemperature("Brest", 500) }
        angers.await() to brest.await()
    }
    display("1 - Angers: $angers, Brest: $brest")

    // 2 - a primeira resposta basta: as outras subtarefas são canceladas
    val first = coroutineScope {
        val mirrors = listOf(
            async { readTemperature("mirror-paris", 800) },
            async { readTemperature("mirror-lyon", 300) })
        select { mirrors.forEach { mirror -> mirror.onAwait { it } } }
            .also { mirrors.forEach { it.cancel() } }
    }
    display("2 - first answer: $first")

    // 3 - código bloqueante em threads virtuais: a falha de uma subtarefa interrompe a outra
    Executors.newVirtualThreadPerTaskExecutor().asCoroutineDispatcher().use { virtuals ->
        try {
            coroutineScope {
                async(virtuals) { runInterruptible { readTemperatureBlocking("Colmar", 1000) } }
                async(virtuals) { runInterruptible { readTemperatureBlocking("", 200) } }
            }
        } catch (e: IllegalArgumentException) {
            display("3 - failure: ${e.message}")
        }
    }
}

// uma leitura que suspende a corrotina
suspend fun readTemperature(city: String, duration: Long): Int {
    delay(duration)
    return 10 + city.length
}

// uma leitura bloqueante, que exibe sua interrupção
fun readTemperatureBlocking(city: String, duration: Long): Int {
    try {
        Thread.sleep(duration)
    } catch (e: InterruptedException) {
        display("    $city: read interrupted, by ${Thread.currentThread()}")
        throw e
    }
    require(city.isNotEmpty()) { "unknown city" }
    return 10 + city.length
}

// exibição com o tempo decorrido desde [start]
fun display(message: String) = println("%5d ms : %s".format(start.elapsedNow().inWholeMilliseconds, message))

Resultados:

1
2
3
4
5
> gradlew -q run -Pmain=async32.Async32Kt
 1023 ms : 1 - Angers: 16, Brest: 15
 1403 ms : 2 - first answer: 21
 1625 ms :     Colmar: read interrupted, by VirtualThread[#22]/runnable@ForkJoinPool-1-worker-2
 1628 ms : 3 - failure: unknown city

Comentários:

  • linhas 19–23: o bloco [coroutineScope] age como um escopo Java: as duas subtarefas lançadas por [async] são suas filhas; ele só termina quando elas terminam e, se uma falha, a outra é abortada e a exceção é relançada. O bloco retorna um par ([to], Capítulo 3), desempacotado por uma atribuição por desestruturação. A duração do conjunto é a da subtarefa mais longa, um segundo (linha 2 dos resultados). Não há [try] com recurso, nem [join()] ou [Subtask.get()]: o escopo é um bloco de código, e o resultado de uma subtarefa é o resultado de [await()];
  • linhas 27–33: a política “a primeira resposta basta” é implementada usando [select] (programa [Async13.kt]), que espera a primeira subtarefa concluída e depois cancela todas as outras (cancelar uma corrotina concluída não tem efeito). Sem esses cancelamentos, o bloco [coroutineScope] esperaria o espelho de Paris terminar. A resposta chega após 300 ms (linha 3);
  • linhas 37–45: desta vez, as subtarefas executam código bloqueante ([Thread.sleep]) em um dispatcher cujas threads são threads virtuais (programa [Async09.kt]). A função [runInterruptible] (programa [Async19.kt]) converte o cancelamento da corrotina em uma interrupção da thread que executa o código bloqueante. A segunda subtarefa falha após 200 ms ([require] lança uma [IllegalArgumentException]); o escopo então cancela a primeira, e [runInterruptible] interrompe sua thread virtual, cujo [Thread.sleep] lança uma [InterruptedException] (linha 4 da saída: a thread que exibe a mensagem é uma [VirtualThread], montada em uma thread portadora do [ForkJoinPool]). A exceção original é então lançada por [coroutineScope] (linha 5). É exatamente assim que [StructuredTaskScope] se comporta: a concorrência estruturada de Kotlin também se aplica ao código bloqueante;
  • o dispatcher de threads virtuais é fechado por [use] ao final do bloco, o que encerra seu executor.

9.14.2. Quando escolher um ou outro?

Threads virtuais e corrotinas resolvem o mesmo problema: escrever, de forma sequencial e legível, código que espera muito (por E/S), sem bloquear uma thread do sistema durante a espera. Elas o fazem de duas maneiras opostas:

 
Threads virtuais (Java 21)
Corrotinas (Kotlin)
Onde está o mecanismo
na JVM: a pilha da thread virtual é copiada para o heap durante uma espera
no compilador e em uma biblioteca: uma função [suspend] é transformada em uma máquina de estados
O que suspende
qualquer operação bloqueante do JDK ([Thread.sleep], sockets, [BlockingQueue], locks)
somente as funções de suspensão ([delay], [await], [send]…); o código bloqueante deve ser tratado pelo o dispatcher [IO]
Código existente
inalterado: qualquer biblioteca bloqueante (JDBC, cliente HTTP) se beneficia disso sem modificação
São necessárias versões [suspend] da API, ou adaptadores ([await()], [withContext(Dispatchers.IO)])
Marcação no código
Nenhuma: um método bloqueante parece igual a qualquer outro
A palavra-chave [suspend] identifica as funções que podem esperar (as chamadas “funções coloridas”)
concorrência estruturada
[StructuredTaskScope], ainda em preview no Java 25
[coroutineScope], [supervisorScope], [Job]: estável desde 2018, no centro do modelo
cancelamento
interrupção de thread ([Thread.interrupt]), à qual cada biblioteca reage à sua maneira
cancelamento cooperativo, propagado pela árvore de corrotinas, com [CancellationException], [withTimeout], [NonCancellable]
fluxos de valores, canais
[Stream] bloqueantes, [BlockingQueue], [java.util.concurrent.Flow]
[Flow], [Channel], [SharedFlow], [StateFlow], com seus operadores
escolha da thread
nenhuma: uma thread virtual executa em qualquer portadora
dispatchers ([Main], [Default], [IO], [limitedParallelism])
plataformas
JVM (21 em diante)
JVM, Android (todas as versões), JavaScript, nativo (Kotlin Multiplatform)
Custo de uma tarefa pendente
algumas centenas de bytes a alguns KB (a pilha copiada)
algumas dezenas a algumas centenas de bytes (o objeto de continuação)

Não se trata de escolher um em vez do outro: eles podem ser combinados, como mostra a Parte 3 do programa [Async32.kt]. Alguns pontos de referência:

  • Para um programa Kotlin que orquestra operações assíncronas (lançar, esperar, combinar, limitar, cancelar e difundir valores), as corrotinas são a escolha natural: elas oferecem concorrência estruturada, cancelamento, fluxos e dispatchers, recursos que as threads virtuais sozinhas não oferecem (ou ainda não oferecem);
  • Para código bloqueante que não pode ser reescrito (um driver JDBC, uma biblioteca Java que faz E/S bloqueante), as threads virtuais evitam que as 64 threads do dispatcher [IO] se esgotem: elas são usadas como dispatcher ([Executors.newVirtualThreadPerTaskExecutor().asCoroutineDispatcher()]) ou diretamente, em um servidor que processa cada requisição em uma thread virtual (o Spring Boot pode fazer isso);
  • no Android, ou em código Kotlin Multiplatform, só há corrotinas disponíveis;
  • o código Java que chama código Kotlin não pode chamar diretamente uma função de suspensão: em vez disso, recebe uma função comum que retorna um [CompletableFuture] (usando a função [future { … }] do programa [Async04.kt]) ou uma função bloqueante (usando [runBlocking]) que o Java chamará em uma thread virtual.

9.15. Aplicação: cálculo do imposto com corrotinas

O programa [Async33.kt] reúne várias ferramentas deste capítulo relacionadas ao cálculo do imposto tratado no fio condutor. Como o programa Java, ele é autônomo (não usa as camadas da Versão 5 do Capítulo 6): lê as faixas do imposto no arquivo [TaxData.txt], já utilizado, e lê uma lista de contribuintes no arquivo [taxpayers.txt], também localizado na raiz do projeto:

1
2
3
4
5
6
7
y 2 60000
y 3 60000
n 0 60000
n 2 25000
y 5 120000
x 1 20000
y 1 -5

(cada linha contém: casado [y/n], número de filhos, salário anual), calcula o imposto de cada contribuinte e grava os resultados no arquivo [results.txt]. As duas leituras são realizadas simultaneamente por duas corrotinas, e todo o processamento é limitado a 10 segundos. Em seguida, o programa calcula os impostos de um milhão de contribuintes imaginários, primeiro de forma sequencial e depois em paralelo:

// aplicação: o cálculo do imposto com corrotinas
// - as faixas são lidas de [TaxData.txt] (ou do arquivo passado como argumento), os contribuintes
//   de [taxpayers.txt]: as duas leituras são feitas ao mesmo tempo, no dispatcher IO
// - os resultados são gravados em [results.txt]
// - depois o imposto de um grande número de contribuintes é calculado em paralelo, no dispatcher Default
package async33

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.TimeoutCancellationException
import kotlinx.coroutines.async
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withContext
import kotlinx.coroutines.withTimeout
import java.io.IOException
import java.math.BigDecimal
import java.math.MathContext
import java.nio.file.Path
import kotlin.io.path.bufferedWriter
import kotlin.io.path.readLines
import kotlin.io.path.readText
import kotlin.io.path.useLines
import kotlin.random.Random
import kotlin.time.Duration.Companion.seconds
import kotlin.time.measureTimedValue

// uma linha correta de contribuinte: casado (y/n), número de filhos, salário anual
val TAXPAYER = Regex("""([yn])\s+(\d+)\s+(\d+)""")

fun main(args: Array<String>) = runBlocking<Unit> {
    val results = Path.of("results.txt")
    val brackets = Path.of(args.getOrElse(0) { "TaxData.txt" })
    try {
        // 1 - todo o processamento é limitado a 10 segundos
        val nbResults = withTimeout(10.seconds) {
            process(brackets, Path.of("taxpayers.txt"), results)
        }
        println("$nbResults lines written to [$results]:")
        print(withContext(Dispatchers.IO) { results.readText() })
    } catch (e: TimeoutCancellationException) {
        println("processing abandoned: timeout exceeded")
        return@runBlocking
    } catch (e: IOException) {
        // o erro de uma leitura chega aqui tal como está
        println("error: ${e::class.simpleName} : ${e.message}")
        return@runBlocking
    }

    // 2 - um cálculo puro, sobre um grande número de contribuintes: em sequência e depois em paralelo
    val scale = withContext(Dispatchers.IO) { loadBrackets(brackets) }
    val random = Random(2026)
    val crowd = List(1_000_000) {
        Taxpayer(random.nextBoolean(), random.nextInt(0, 5), random.nextInt(10_000, 150_000))
    }
    val (total1, duration1) = measureTimedValue { crowd.sumOf { calculateTax(scale, it).toLong() } }
    println("2 - in sequence: total = %,d €, in %d ms".format(total1, duration1.inWholeMilliseconds))
    val (total2, duration2) = measureTimedValue {
        withContext(Dispatchers.Default) {
            // um lote de contribuintes por corrotina, tantos lotes quantos processadores
            val size = crowd.size / Runtime.getRuntime().availableProcessors() + 1
            crowd.chunked(size)
                .map { batch -> async { batch.sumOf { calculateTax(scale, it).toLong() } } }
                .awaitAll()
                .sum()
        }
    }
    println("2 - in parallel: total = %,d €, in %d ms".format(total2, duration2.inWholeMilliseconds))
}

// os dois arquivos são lidos ao mesmo tempo; o cálculo espera as duas leituras e depois grava os resultados
suspend fun process(bracketsFile: Path, taxpayersFile: Path, output: Path): Int = coroutineScope {
    val brackets = async(Dispatchers.IO) { loadBrackets(bracketsFile) }
    val taxpayers = async(Dispatchers.IO) { taxpayersFile.readLines() }
    calculateTaxes(brackets.await(), taxpayers.await(), output)
}

// lê as faixas de imposto (limit:coeffR:coeffN, ponto decimal) ignorando as linhas vazias
fun loadBrackets(file: Path): List<TaxBracket> =
    file.useLines { lines -> lines.filter { it.isNotBlank() }.map(TaxBracket::parse).toList() }

// calcula o imposto de cada contribuinte e grava os resultados (E/S: no dispatcher IO)
suspend fun calculateTaxes(brackets: List<TaxBracket>, taxpayers: List<String>, output: Path): Int =
    withContext(Dispatchers.IO) {
        output.bufferedWriter().use { writer ->
            for (line in taxpayers) {
                val result = TAXPAYER.matchEntire(line.trim())?.destructured
                    ?.let { (married, children, salary) ->
                        val taxpayer = Taxpayer(married == "y", children.toInt(), salary.toInt())
                        "tax = ${calculateTax(brackets, taxpayer)} €"
                    }
                    ?: "incorrect line"
                writer.write("%-12s : %s".format(line, result))
                writer.newLine()
            }
        }
        taxpayers.size
    }

// o cálculo do imposto (tabela de 2004 sobre a renda de 2003, mantida para o exercício)
fun calculateTax(brackets: List<TaxBracket>, taxpayer: Taxpayer): Int {
    val (married, nbChildren, salary) = taxpayer
    var shares = BigDecimal(nbChildren).divide(BigDecimal.TWO) + BigDecimal(if (married) 2 else 1)
    if (nbChildren >= 3) shares += BigDecimal("0.5")
    val income = BigDecimal("0.72") * BigDecimal(salary)
    val quotient = income.divide(shares, MathContext.DECIMAL64)
    // a primeira faixa cujo limite excede o quociente familiar, caso contrário a última
    val bracket = brackets.firstOrNull { quotient <= it.limit } ?: brackets.last()
    return (bracket.coeffR * income - bracket.coeffN * shares).toInt()
}

// um contribuinte
data class Taxpayer(val married: Boolean, val nbChildren: Int, val salary: Int)

// uma faixa de imposto
data class TaxBracket(val limit: BigDecimal, val coeffR: BigDecimal, val coeffN: BigDecimal) {
    companion object {
        fun parse(line: String): TaxBracket {
            val (limit, coeffR, coeffN) = line.split(":").map(::BigDecimal)
            return TaxBracket(limit, coeffR, coeffN)
        }
    }
}

Resultados:

> gradlew -q run -Pmain=async33.Async33Kt
7 lines written to [results.txt]:
y 2 60000    : tax = 4282 €
y 3 60000    : tax = 2959 €
n 0 60000    : tax = 11519 €
n 2 25000    : tax = 792 €
y 5 120000   : tax = 11109 €
x 1 20000    : incorrect line
y 1 -5       : incorrect line
2 - in sequence: total = 11,374,472,918 €, in 338 ms
2 - in parallel: total = 11,374,472,918 €, in 145 ms

O mesmo programa, com o nome de um arquivo de faixas inexistente como argumento (a opção [--args] da tarefa Gradle [run] repassa seus argumentos ao programa):

> gradlew -q run -Pmain=async33.Async33Kt --args="Missing.txt"
Error: NoSuchFileException : Missing.txt

Comentários:

  • linhas 72–75: o processamento é uma função de suspensão cujo corpo é um bloco [coroutineScope]. Os dois arquivos de entrada são lidos simultaneamente por duas corrotinas lançadas por [async] no dispatcher [IO], usando funções de leitura bloqueantes comuns ([useLines], [readLines]); o cálculo espera as duas leituras com [await()]. O programa Java precisava lançar o cálculo como uma terceira tarefa, que bloquearia uma thread virtual enquanto esperasse as duas leituras; aqui, o cálculo é simplesmente a continuação do código;
  • linhas 35–42: o programa principal limita o processamento a 10 segundos usando [withTimeout]. Passado esse prazo, o processamento seria cancelado, isto é, as duas leituras e o cálculo, sem exigir nenhum código adicional: isso é concorrência estruturada. A expressão [return@runBlocking] sai da lambda de [runBlocking] e, portanto, do programa (Capítulo 7: um [return] com rótulo);
  • linhas 44–46: os erros são tratados em um único lugar, no programa principal. Um erro de leitura (arquivo ausente, número incorreto) faz a corrotina de leitura falhar; o bloco [coroutineScope] então cancela a outra leitura e relança a exceção original, que chega sem alterações ao [catch] (segundo resultado). O programa Java recebia essa exceção encapsulada duas vezes em uma [ExecutionException] e precisava desencapsulá-la em um laço: a concorrência estruturada eliminou esse inconveniente, como explicado no curso de Java;
  • linha 33: o nome do arquivo de faixas é o primeiro argumento do programa, se houver; caso contrário, [getOrElse] retorna o valor calculado pela lambda;
  • linhas 79–80: leitura das faixas, usando a sequência de linhas do arquivo ([useLines]), que ignora as linhas vazias;
  • linhas 83–97: processamento dos contribuintes, que grava em um arquivo; ele, portanto, transfere a si mesmo ao dispatcher [IO], conforme a regra definida pelo programa [Async21.kt]. Cada linha é validada pela expressão regular da linha 29: um [y] ou um [n], seguido de dois inteiros positivos separados por espaços ([\s+]); a raw string (["""…"""]) evita que as barras invertidas sejam duplicadas. [matchEntire] retorna o resultado da correspondência se a linha inteira casar com a expressão, [null] caso contrário; sua propriedade [destructured] permite recuperar os três grupos por uma atribuição por desestruturação, em [let]. O operador Elvis ([?:]) retorna o texto “incorrect line” quando a linha não corresponde ([x] em vez de [y/n], salário negativo);
  • linhas 101–109: o cálculo do imposto, em [BigDecimal], escrito com os operadores [+], [*], [-], e [<=], que Kotlin permite para esse tipo. A divisão da renda pelo número de partes pode não ser exata: ela é feita com [divide] com precisão de 16 dígitos significativos ([MathContext.DECIMAL64]), e não com o operador [/], que arredondaria o quociente para o número de casas decimais do dividendo. A primeira faixa cujo limite é maior ou igual ao quociente familiar é encontrada com [firstOrNull], e o operador Elvis retorna a última faixa se nenhuma das outras servir. [toInt()] trunca o imposto para o euro inteiro. O contribuinte é uma data class, decomposta por uma declaração de desestruturação;
  • os resultados fornecem os valores de controle do fio condutor: 4.282 € para um casal com 2 filhos e salário de 60.000 €, 2.959 € com 3 filhos e 11.519 € para uma pessoa solteira sem filhos;
  • linhas 50–68: um milhão de contribuintes fictícios são gerados por um gerador de números pseudoaleatórios ([Random]) cuja semente fixa (2026) garante resultados reproduzíveis. Seus impostos são primeiro somados em sequência ([sumOf], depois [Long] para evitar que o [Int] estoure a capacidade). Em seguida, são divididos em tantos pacotes ([chunked]) quantos processadores a máquina tem; cada pacote é atribuído a uma corrotina do dispatcher [Default], que tem tantas threads quantos processadores, e [awaitAll()] calcula as somas parciais. O total é o mesmo, e o cálculo é mais rápido nesta máquina de dois processadores (o ganho aparente é até maior que 2, porque a primeira medição inclui o tempo que a JVM leva para compilar o código do cálculo em código de máquina).

Calcular o imposto de um contribuinte é síncrono: não envolve E/S e leva alguns microssegundos. Seria inútil, e até prejudicial, torná-lo uma função suspensível ou delegá-lo a outra thread: somente as tarefas que envolvem espera devem ser tornadas assíncronas. Por outro lado, um grande número de cálculos independentes pode ser distribuído entre os processadores: esse é o papel do dispatcher [Default] (ou dos streams paralelos tratados no Capítulo 8), e não o do dispatcher [IO] nem o das threads virtuais, que lidam com operações de espera.

9.16. As regras de ouro

Vamos resumir as regras da programação assíncrona com corrotinas:

  • Para esperar, suspenda; não bloqueie: em uma corrotina, a espera é feita por uma função de suspensão ([delay], [await()], [send], [receive], [withContext]…), nunca por [Thread.sleep], [join()] ou [get()] de um [Future]. [runBlocking] só tem lugar no programa principal e nos testes;
  • uma função de suspensão bloqueante transfere ela mesma o controle ao dispatcher correto: o código bloqueante (arquivos, JDBC, bibliotecas Java) é entregue a [Dispatchers.IO] por [withContext(Dispatchers.IO)], dentro da função bloqueante; o chamador pode então chamá-la de qualquer lugar. Uma API que retorna um [CompletableFuture] é combinada com [await()]; uma API baseada em callbacks é combinada com [suspendCancellableCoroutine];
  • Dispatchers.Default para cálculos, Dispatchers.IO para esperas bloqueantes, Dispatchers.Main para a interface; uma visão [limitedParallelism(n)] para reservar um número de threads para um recurso bloqueante; threads virtuais atuando como dispatcher quando há milhares de esperas bloqueantes;
  • toda corrotina tem um pai: as corrotinas são lançadas dentro de um escopo ([coroutineScope], o escopo de um componente, [viewModelScope]…), nunca em [GlobalScope]; um escopo espera seus filhos; se um filho falha, os outros são cancelados ([supervisorScope] para torná-los independentes), e cancelar um pai cancela seus filhos. Uma função que lança corrotinas sem esperá-las é uma extensão de [CoroutineScope]; uma função que espera o término de seu trabalho é uma função [suspend];
  • lance primeiro, espere depois: para executar várias operações independentes simultaneamente, lance todas ([async]) e depois espere por elas ([awaitAll()]);
  • o cancelamento é cooperativo: uma corrotina para em seus pontos de suspensão; um cálculo longo verifica [isActive] ou chama [ensureActive()] / [yield()]; uma [CancellationException] nunca é engolida (cuidado com [catch (e: Exception)] e [runCatching]); a limpeza de uma corrotina cancelada que precise suspender é feita em [withContext(NonCancellable)];
  • Limite os tempos de espera: [withTimeout] e [withTimeoutOrNull] cancelam a própria operação, e não apenas a espera; um [CompletableDeferred] com timeout deve ser cancelado por seu criador;
  • Limite as operações concorrentes usando um semáforo ([withPermit]) ou um número fixo de workers que leem um [Channel]; [limitedParallelism] limita threads, não operações suspensas;
  • Uma sequência de valores é um Flow: frio, coletado sob demanda, transformado por operadores; [flowOn] para mudar o dispatcher do produtor, [buffer] para desacoplar produtor e consumidor, [catch] para erros a montante. As fontes quentes são [Channel] (um consumidor por valor), [SharedFlow] (todos os assinantes) ou [StateFlow] (um estado);
  • Nenhum lock de thread em torno de uma suspensão: [synchronized] e [ReentrantLock] não devem envolver uma chamada de suspensão; use um [Mutex]ou, melhor ainda, evite o estado compartilhado (um [Deferred] compartilhado, um canal, dados imutáveis).

A tabela a seguir resume as equivalências entre o mundo das threads de plataforma e das esperas bloqueantes (capítulo anterior), o das threads virtuais e do [CompletableFuture] (curso de Java) e o das corrotinas:

Threads, esperas bloqueantes
Threads virtuais, CompletableFuture
Corrotinas
[Thread.sleep(1000)] (bloqueia a thread)
[Thread.sleep(1000)] em uma thread virtual (libera a portadora)
[delay(1000)] (suspende a corrotina)
[thread { … }] seguido de [join()]
[executor.submit { … }] depois [get()]; [supplyAsync { … }] depois [join()]
[launch { … }] seguido de [join()]; [async { … }] seguido de [await()]
Esperar várias threads ([join] em um laço)
[invokeAll(...)], [allOf(...)], [anyOf(...)]
[awaitAll()], [coroutineScope], [select]
Métodos de callback ([CompletionHandler])
[thenApply], [thenCompose], [thenCombine]
O código que segue a chamada de suspensão
[try / catch] em torno de [get()] ([ExecutionException])
[exceptionally], [handle], [whenComplete]
[try / catch] (comum), [CoroutineExceptionHandler]
[thread.interrupt()]
[future.cancel(true)]
[job.cancel()] (cancelamento cooperativo, propagado aos filhos)
[future.get(timeout, unit)]
[orTimeout(...)], [completeOnTimeout(...)]
[withTimeout(...)], [withTimeoutOrNull(...)]
pool de threads de tamanho fixo
[Semaphore] ([java.util.concurrent])
[Semaphore] ([kotlinx.coroutines.sync]), [limitedParallelism(n)]
[BlockingQueue] (bloqueia a thread)
[BlockingQueue] em threads virtuais, [SubmissionPublisher]
[Channel], [SharedFlow]
[Stream], [Iterator]
[Stream], um lock lido por uma thread virtual
[Flow]
[synchronized], [ReentrantLock]
[ReentrantLock]
[Mutex]
[ScheduledExecutorService]
[ScheduledExecutorService], [delayedExecutor]
[delay] em um laço
—
[new CompletableFuture<>()], [complete]
[CompletableDeferred], [suspendCancellableCoroutine]
—
[StructuredTaskScope] (preview)
[coroutineScope], [supervisorScope]

Os capítulos seguintes aplicarão essas regras: o acesso a bancos de dados com JDBC (Capítulo 10) e Hibernate (Capítulo 11), em que as chamadas de API são bloqueantes e são usadas a partir de corrotinas no dispatcher [IO] (ou em threads virtuais), o servidor TCP, que atende cada cliente por meio de uma thread virtual ou de uma corrotina, e o cliente [HttpClient] (Capítulo 12), bem como os serviços web Spring Boot e seus clientes (Capítulo 13).