Skip to content

9. Programação assíncrona

O capítulo anterior apresentou as threads: podemos 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 uma questão relacionada, porém distinta: como escrever um programa que espera muito (pelo disco, pela rede ou por um banco de dados) sem prender threads durante essas esperas.

Java não possui palavras-chave da linguagem para isso (outras linguagens, como C# ou JavaScript, têm as palavras-chave [async] e [await]). Ele oferece duas soluções, que se complementam e são ambas apresentadas neste capítulo:

  • a classe [CompletableFuture<T>] (Java 8, aprimorada desde então) representa uma operação em andamento cujas etapas seguintes são compostas por meio de métodos de callback: “quando o resultado estiver pronto, faça isto, depois aquilo” ([thenApply], [thenCompose], [thenCombine], [allOf]…). Nenhuma thread espera: é a conclusão da operação que dispara a etapa seguinte;
  • as threads virtuais (Java 21), por outro lado, permitem escrever código bloqueante e sequencial, que se lê de cima para baixo: quando uma thread virtual espera por uma entrada/saída, a JVM a separa da thread do sistema que a executava (sua “thread portadora”) e libera essa thread para outra thread virtual. Isso torna possível ter centenas de milhares de threads virtuais para apenas algumas threads do sistema. Essa é a solução moderna do Java para o problema que outras linguagens resolvem com [async] / [await].

Essas ferramentas estão por toda parte hoje: os capítulos seguintes as explorarão para acessar bancos de dados, escrever servidores TCP que atendem cada cliente por meio de uma thread virtual, clientes web que usam [java.net.http.HttpClient] e serviços web com Spring Boot.

Todos os exemplos deste capítulo são arquivos-fonte compactos ([Async01.java], [Async02.java]…) executados com [java AsyncNN.java] na pasta [09-async]. Muitos deles medem tempos de execução com [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 de dois processadores). O que importa são as ordens de grandeza: 1 segundo ou 10 segundos, 300 ms ou 0 ms.

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 periférico: ler um arquivo do disco, enviar uma requisição a um servidor web e esperar sua 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 leitura em um disco (SSD) leva da ordem de um décimo de milissegundo; uma ida e volta em uma rede local leva uma fração de milissegundo; uma ida e volta a um servidor situado do outro lado do país leva algumas dezenas de milissegundos; e uma consulta 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 um método bloqueante, a thread que realiza essa leitura fica bloqueada: ela não faz nada, mas continua existindo. Uma thread Java “clássica” — hoje chamada de “thread de plataforma” — é uma thread do sistema operacional: 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 é problema em um pequeno programa de console que faz uma coisa de cada vez. Torna-se um problema bem maior 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 as N threads estão realizando uma operação bloqueante, não resta nenhuma thread disponível para um novo cliente. Um servidor moderno trata 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: uma única thread — a thread da interface (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.

A assincronia consiste em iniciar a operação de E/S, liberando a thread do sistema enquanto ela está em andamento (o hardware e o sistema operacional não precisam dela para transferir os dados), e depois retomar o trabalho quando a operação termina, possivelmente em outra thread do sistema:

Image

  • Em [1], a thread de plataforma T1 inicia a E/S e permanece bloqueada até que ela termine;
  • em [2], a thread virtual V1 inicia a E/S; a JVM a separa de sua thread portadora P1, que pode então executar imediatamente outras threads virtuais. Quando a E/S termina, a JVM reanexa V1 a uma thread portadora livre, P2 (que também poderia ser P1), e V1 continua sua execução imediatamente após a instrução bloqueante, como se nada tivesse acontecido.

O programa [Async01.java] 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 ([Executors.newVirtualThreadPerTaskExecutor], [CompletableFuture]): aqui, o que nos interessa são principalmente os resultados.

// por que a 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…)
import java.lang.management.ManagementFactory;

final int nbOperations = 100;
long start;

void main() throws InterruptedException {
    IO.println(nbOperations + " operations of one second, "
            + Runtime.getRuntime().availableProcessors() + " processors");

    // 1 - uma thread de plataforma por operação, cada thread fica bloqueada durante a espera
    start = System.nanoTime();
    List<Thread> threads = new ArrayList<>();
    for (int i = 0; i < nbOperations; i++) {
        threads.add(Thread.ofPlatform().start(() -> waitFor(1000)));
    }
    display("1 - one platform thread per operation", jvmThreads());
    for (Thread thread : threads) {
        thread.join();
    }
    display("    end", -1);

    // 2 - as operações são entregues a um pool de 10 threads, mas elas o bloqueiam
    start = System.nanoTime();
    try (ExecutorService pool = Executors.newFixedThreadPool(10)) {
        for (int i = 0; i < nbOperations; i++) {
            pool.submit(() -> waitFor(1000));
        }
        display("2 - pool of 10 threads, blocking waits", jvmThreads());
    } // close() espera o fim de todas as operações
    display("    end", -1);

    // 3 - uma thread virtual por operação: ela libera sua thread carrier durante a espera
    start = System.nanoTime();
    try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
        for (int i = 0; i < nbOperations; i++) {
            executor.submit(() -> waitFor(1000));
        }
        display("3 - one virtual thread per operation", jvmThreads());
    }
    display("    end", -1);

    // 4 - esperas assíncronas: nenhuma thread espera, um timer conclui cada operação
    start = System.nanoTime();
    var operations = new CompletableFuture<?>[nbOperations];
    for (int i = 0; i < nbOperations; i++) {
        operations[i] = new CompletableFuture<Void>().completeOnTimeout(null, 1000, TimeUnit.MILLISECONDS);
    }
    display("4 - asynchronous waits (CompletableFuture)", jvmThreads());
    CompletableFuture.allOf(operations).join();
    display("    end", -1);
}

// uma espera bloqueante de [ms] milissegundos
void waitFor(long ms) {
    try {
        Thread.sleep(ms);
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
    }
}

// número de threads de plataforma da JVM, meio segundo depois do início das operações
int jvmThreads() {
    long elapsed = (System.nanoTime() - start) / 1_000_000;
    if (elapsed < 500) {
        waitFor(500 - elapsed);
    }
    return ManagementFactory.getThreadMXBean().getThreadCount();
}

// exibição do tempo decorrido e, se informado (>= 0), do número de threads
void display(String message, int nbThreads) {
    String threadsInfo = nbThreads < 0 ? "" : String.format(", %3d threads in the JVM", nbThreads);
    long elapsed = (System.nanoTime() - start) / 1_000_000;
    IO.println(String.format("%-44s : %5d ms%s", message, elapsed, threadsInfo));
}

Resultados:

> java Async01.java
100 operations of one second, 2 processors
1 - one platform thread per operation        :   534 ms, 106 threads in the JVM
    end                                      :  1061 ms
2 - pool of 10 threads, blocking waits       :   501 ms,  16 threads in the JVM
    end                                      : 10021 ms
3 - one virtual thread per operation         :   501 ms,  10 threads in the JVM
    end                                      :  1091 ms
4 - asynchronous waits (CompletableFuture)   :   500 ms,  11 threads in the JVM
    end                                      :  1003 ms

Comentários:

  • Linhas 12–22: a solução mais simples — uma thread de plataforma por operação. [Thread.ofPlatform().start(task)] (Java 21) cria e inicia uma thread, assim como [new Thread(task).start()]. 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 tem 106 delas (linha 3). Com 10.000 operações, seriam necessárias 10.000 threads de sistema;
  • Linhas 24–32: 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 estão calculando — estão ociosas. As operações esperam uma thread livre, em lotes de 10, e o processo inteiro leva… dez segundos (linha 6). Isso é conhecido como “thread pool starvation” (inanição do pool de threads), a falha mais comum em servidores que misturam pools de threads com E/S bloqueante. O método [close()] de um executor (Java 19), chamado na saída do [try], rejeita novas tarefas e espera que as já submetidas terminem;
  • Linhas 34–42: uma thread virtual por operação. [Executors.newVirtualThreadPerTaskExecutor()] (Java 21) devolve um executor que cria uma nova thread virtual para cada tarefa submetida. O código da tarefa é o mesmo da Etapa 1: um [Thread.sleep(1000)] bloqueante. No entanto, uma thread virtual bloqueada não prende uma thread de sistema: a JVM a separa de sua thread portadora. As 100 esperas duram um segundo no total (linha 8), e a JVM conta apenas 10 threads de sistema (linha 7): suas threads de serviço e as duas threads portadoras — uma por processador — que executaram as 100 threads virtuais. As threads virtuais não entram nessa contagem: são objetos da JVM, não threads de sistema;
  • linhas 44–52: a mesma espera sem nenhuma thread esperando. [new CompletableFuture<Void>()] cria uma operação “pendente”, e [completeOnTimeout(value, timeout, unit)] (Java 9) pede que ela seja concluída com o valor especificado quando o tempo limite expirar. Um único timer da JVM gerencia os 100 tempos limite. [CompletableFuture.allOf(...)] devolve uma operação que termina quando todas as outras terminaram, e [join()] espera que ela termine. O processo inteiro dura um segundo (linha 10), com apenas uma thread adicional em relação à etapa 3 — a thread do timer (linha 9);
  • linhas 55–62: [Thread.sleep] pode lançar a exceção verificada [InterruptedException] se a thread for interrompida durante o sono (voltaremos a isso na seção sobre cancelamento); o método [waitFor] a intercepta para que as lambdas das linhas 16, 28 e 38 não precisem tratá-la;
  • Linhas 64–71: [ManagementFactory.getThreadMXBean().getThreadCount()] devolve o número de threads de plataforma vivas da JVM. A classe [ManagementFactory] pertence ao módulo [java.management]: um arquivo-fonte compacto importa automaticamente apenas o módulo [java.base], daí o import da linha 3.

Guardemos a lição: para esperar, não se deve bloquear nenhuma thread de sistema. A assincronia não torna a E/S mais rápida; ela permite tratar um grande número de operações de E/S simultaneamente com poucas threads de sistema, mantendo disponíveis as threads de que a aplicação precisa. Java oferece duas abordagens para isso: criar [CompletableFuture] (Etapa 4) ou escrever código bloqueante comum executado por threads virtuais (Etapa 3).

9.1.2. Vários modelos sucessivos

Java ofereceu várias maneiras de escrever código que espera sem bloquear. Os mais antigos ainda são encontrados em código existente, portanto é útil reconhecê-los.

Modelo
Introdução
Princípio
[Future] e Runtimes
Java 5 (2004)
[ExecutorService.submit] atribui uma tarefa a um pool de threads e devolve 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 do NIO.2
Java 7 (2011)
Os canais assíncronos ([AsynchronousSocketChannel], [AsynchronousFileChannel]) iniciam uma operação e recebem um objeto de callback ([CompletionHandler]) cujo método [completed] ou [failed] é chamado por uma thread de um pool quando a operação termina.
[CompletableFuture]
Java 8 (2014)
um [Future] que você mesmo pode concluir e cuja sequência é composta por métodos de callback ([thenApply], [thenCompose], [exceptionally]…); os streams reativos [java.util.concurrent.Flow] (Java 9) são uma extensão disso para sequências de valores. As bibliotecas reativas (Project Reactor, usado pelo Spring WebFlux, RxJava) baseiam-se nos mesmos conceitos.
threads virtuais
Java 21 (2023)
código bloqueante comum, executado por threads virtuais: a JVM libera a thread de sistema durante as esperas. Esse é hoje o modelo recomendado para novas aplicações.
concorrência estruturada
Prévia do Java 21 ao Java 25
[StructuredTaskScope] organiza um grupo de subtarefas executadas por threads virtuais como um único bloco de código, com tratamento de erros e cancelamento compartilhados (veja o final do capítulo).

Os métodos de callback têm uma desvantagem: o código fica fragmentado. O que naturalmente se lê como “conectar, depois ler, depois exibir” torna-se um método que inicia a conexão, um método de callback que inicia a leitura e outro método de callback que exibe o resultado; as variáveis precisam ser compartilhadas entre esses métodos, as exceções são capturadas em locais diferentes, e um simples laço (“ler enquanto houver dados”) torna-se um método de callback que chama a si mesmo recursivamente. [CompletableFuture] torna essa fragmentação mais legível ao encadear as etapas; as threads virtuais a fazem desaparecer: o código assíncrono assume a forma de código síncrono, porque ele é código síncrono.

O programa [Async02.java] implementa o mesmo cliente TCP usando duas abordagens extremas: primeiro com os métodos de callback do NIO.2 e depois com código bloqueante executado por uma thread virtual. Ele contém também um pequeno servidor, executado por uma thread, que responde a dois clientes (a programação de rede será tratada em detalhe 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, Java 7) e depois com uma thread virtual (Java 21)
final int port = 27500;
final InetAddress local = InetAddress.getLoopbackAddress();
final ByteBuffer buffer = ByteBuffer.allocate(1024);
final CountDownLatch end = new CountDownLatch(1);

void main() throws IOException, InterruptedException {
    // um servidor mínimo, executado por uma thread: atende dois clientes e depois para
    var listener = new ServerSocket(port, 10, local);
    Thread server = Thread.ofPlatform().name("server").start(() -> {
        try (listener) {
            for (int i = 1; i <= 2; i++) {
                try (Socket service = listener.accept()) {
                    // o servidor demora para responder
                    Thread.sleep(500);
                    byte[] message = ("Hello client no. " + i).getBytes(StandardCharsets.UTF_8);
                    service.getOutputStream().write(message);
                }
            }
        } catch (IOException | InterruptedException e) {
            display("server: " + e);
        }
    });
    display("start of the program");

    // 1 - o estilo "métodos de callback": AsynchronousSocketChannel e CompletionHandler
    var client = AsynchronousSocketChannel.open();
    // iniciamos a conexão, passando o objeto a ser chamado de volta quando terminar
    client.connect(new InetSocketAddress(local, port), client, new Connected());
    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 estilo bloqueante, executado por uma thread virtual: o código é lido de cima para baixo
    Thread virtual = Thread.ofVirtual().start(() -> {
        try (var client2 = new Socket(local, port)) {
            display("virtual thread: connected, read started");
            byte[] bytes = new byte[1024];
            int nbBytes = client2.getInputStream().read(bytes);
            String message = new String(bytes, 0, nbBytes, StandardCharsets.UTF_8);
            display("virtual thread: received [" + message + "]");
        } catch (IOException e) {
            display("virtual thread: " + e);
        }
    });
    virtual.join();
    server.join();
}

// método de callback nº 1: a conexão foi feita (ou falhou)
class Connected implements CompletionHandler<Void, AsynchronousSocketChannel> {
    @Override
    public void completed(Void nothing, AsynchronousSocketChannel channel) {
        display("callbacks: connected, read started");
        // iniciamos a leitura da resposta do servidor com outro objeto de callback
        channel.read(buffer, channel, new Received());
    }

    @Override
    public void failed(Throwable e, AsynchronousSocketChannel channel) {
        display("callbacks: connection failed: " + e);
        end.countDown();
    }
}

// método de callback nº 2: chegaram dados
class Received implements CompletionHandler<Integer, AsynchronousSocketChannel> {
    @Override
    public void completed(Integer nbBytes, AsynchronousSocketChannel channel) {
        display("callbacks: received [" + new String(buffer.array(), 0, nbBytes, StandardCharsets.UTF_8) + "]");
        try {
            channel.close();
        } catch (IOException e) {
            display("callbacks: " + e);
        }
        // notificamos a thread principal
        end.countDown();
    }

    @Override
    public void failed(Throwable e, AsynchronousSocketChannel channel) {
        display("callbacks: read failed: " + e);
        end.countDown();
    }
}

// exibição prefixada pela thread que a executa
// (nome de uma thread de plataforma, descrição de uma thread virtual)
void display(String message) {
    Thread thread = Thread.currentThread();
    IO.println("[" + (thread.isVirtual() ? thread.toString() : thread.getName()) + "] " + message);
}

Resultados:

1
2
3
4
5
6
7
> java Async02.java
[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]
[VirtualThread[#28]/runnable@ForkJoinPool-1-worker-1] virtual thread: connected, read started
[VirtualThread[#28]/runnable@ForkJoinPool-1-worker-2] virtual thread: received [Hello client no. 2]

Comentários:

  • Linhas 8–23: 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]. A forma [try (listener)] (Java 9) fechará o [ServerSocket] declarado na linha 9 ao final do bloco;
  • linhas 26–32: o cliente escreve usando métodos de callback:
    • linha 27: um *[AsynchronousSocketChannel]* é um canal TCP cujas operações são assíncronas;
    • linha 29: [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, o próprio canal) e o objeto de callback, do tipo [Connected];
    • linha 32: 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 (linha 5), cujo método [await] bloqueia a thread que o chama até que outra thread chame seu método [countDown];
  • linhas 50–64: o objeto de callback da conexão implementa a interface [CompletionHandler<V, A>], em que [V] é o tipo de resultado da operação ([Void] para uma conexão) e [A] é o tipo do objeto repassado. Seu método [completed] é chamado se a operação tem sucesso, e seu método [failed] é chamado se ela falha. Uma vez conectado, a leitura é iniciada com [read] especificando um segundo objeto de callback do tipo [Received] (linha 56);
  • linhas 66–85: o objeto de callback de leitura recebe o número de bytes lidos, exibe a mensagem, fecha o canal e libera a thread principal. As classes [Connected] e [Received] são classes internas da classe implícita do arquivo compacto: elas têm acesso a seus campos [buffer] e [end] e a seu método [display];
  • 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]);
  • linhas 34–46: o mesmo cliente, escrito com um [Socket] comum e operações bloqueantes ([new Socket(...)] conecta, [read] espera dados), executado por uma thread virtual criada por [Thread.ofVirtual().start(task)] (Java 21). O código se lê de cima para baixo como código síncrono; as variáveis são variáveis locais comuns; os erros são tratados por um único [try / catch]; não há métodos de callback nem sinais a gerenciar;
  • linhas 87–92: cada exibição é prefixada com a thread que a executa. Para uma thread virtual, [toString()] devolve uma descrição na forma [VirtualThread[#28]/runnable@ForkJoinPool-1-worker-1]: o número da thread virtual, seu estado e sua thread hospedeira atual. As linhas 6 e 7 dos resultados mostram a mesma thread virtual nº 28, transportada primeiro por [worker-1] e depois por [worker-2]: enquanto esperava a resposta do servidor, ela foi separada de sua primeira thread portadora e depois reanexada a outra.

Não é necessário reter a interface [CompletionHandler]. Se você precisar usar uma API que só oferece esse modelo, converta-a em [CompletableFuture] (faremos isso em [Async17.java]) ou use sua versão bloqueante em uma thread virtual.

9.2. Tarefas futuras: Future e CompletableFuture

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 concluída. Nós o encontramos no capítulo anterior: é o que o método [submit] de um executor devolve. É possível consultá-lo (já 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 duas capacidades essenciais:

  • você pode concluí-lo por conta própria, com um resultado ([complete]) ou uma exceção ([completeExceptionally]);
  • você pode anexar a ele uma operação subsequente — uma função que será executada quando o resultado estiver disponível ([thenApply], [thenAccept], [thenCompose]…), que produz um novo [CompletableFuture]. Dessa forma, constroem-se cadeias de operações sem que nenhuma thread precise esperar. Esses métodos são declarados pela interface [CompletionStage<T>], que [CompletableFuture] também implementa.

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: o da etapa 4 de [Async01.java] é simplesmente “concluído” por um timer após um segundo, e o devolvido por [HttpClient.sendAsync] é concluído quando a resposta do servidor chega. Ele é uma promessa de um resultado.

O programa [Async03.java] demonstra as principais maneiras de criar, consultar e esperar um [CompletableFuture]:

// CompletableFuture: criação, espera, estado, resultado, continuação
void main() throws InterruptedException {
    // 1 - supplyAsync entrega um processamento a um executor e retorna um CompletableFuture<T>
    CompletableFuture<Long> f1 = CompletableFuture.supplyAsync(() -> {
        // um cálculo de algumas décimas de segundo
        long sum = 0;
        for (int i = 1; i <= 200_000_000; i++) {
            sum += i % 7;
        }
        return sum;
    });
    IO.println("f1 started, state: " + f1.state());
    // join() espera o fim do processamento, bloqueando a thread atual, e retorna seu resultado
    long result = f1.join();
    IO.println("f1 finished, state: " + f1.state() + ", result: " + result);

    // 2 - um CompletableFuture concluído por um timer após 300 ms, sem ocupar uma thread
    CompletableFuture<Void> f2 = new CompletableFuture<Void>()
            .completeOnTimeout(null, 300, TimeUnit.MILLISECONDS);
    IO.println("f2 started, state: " + f2.state());
    f2.join();
    IO.println("f2 finished, state: " + f2.state());

    // 3 - CompletableFutures já concluídos, com sucesso ou com falha
    CompletableFuture<Integer> f3 = CompletableFuture.completedFuture(42);
    CompletableFuture<Integer> f4 = CompletableFuture.failedFuture(new IllegalStateException("failure"));
    IO.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
    CompletableFuture<Integer> f5 = CompletableFuture.supplyAsync(() -> Integer.parseInt("abc"));
    try {
        f5.join();
    } catch (CompletionException e) {
        IO.println("f5: state " + f5.state() + ", join() throws " + e.getClass().getSimpleName()
                + " containing " + e.getCause());
    }

    // 5 - get(), herdado da interface Future, encapsula a exceção em uma ExecutionException
    try {
        f5.get();
    } catch (ExecutionException e) {
        IO.println("f5: get() throws " + e.getClass().getSimpleName()
                + " containing " + e.getCause().getClass().getSimpleName());
    }

    // 6 - uma continuação: o que fazer quando o CompletableFuture for concluído
    CompletableFuture<Integer> f6 = f2.thenApply(nothing -> 2 * 21);
    CompletableFuture<Void> f7 = f6.thenAccept(value -> IO.println("f7: the continuation received " + value));
    f7.join();

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

Resultados:

> java Async03.java
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: failure
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 4–11: [CompletableFuture.supplyAsync(supplier)] passa uma função sem parâmetros ([Supplier<T>]) a um executor e devolve imediatamente um [CompletableFuture<T>] que representa sua execução. A função devolve um [long], portanto obtemos um [CompletableFuture<Long>]. Sem um executor explícito, o pool comum da JVM, [ForkJoinPool.commonPool()] , executa a função; veremos mais adiante como escolher o executor. Para um processamento sem resultado ([Runnable]), usamos [runAsync], que devolve um [CompletableFuture<Void>];
  • Linha 12: o método [state()] (Java 19) devolve o estado da operação: [RUNNING] (em andamento), [SUCCESS] (concluída com sucesso), [FAILED] (encerrada por uma exceção) ou [CANCELLED] (cancelada). Essas são as constantes da enumeração [Future.State]; as três últimas são estados finais: uma operação concluída não muda mais de estado;
  • linha 14: [join()] espera a operação terminar e devolve seu resultado. Como [Thread.join] no capítulo anterior, é uma espera bloqueante: a thread atual fica suspensa (no caso, a thread principal, o que não é problema para um pequeno programa de console);
  • Linhas 17–22: um [CompletableFuture] criado como “em andamento” por seu criador e encerrado por um timer após 300 ms ([completeOnTimeout], Java 9). Nenhuma thread fica ocupada durante esse tempo: é o equivalente assíncrono de [Thread.sleep(300)]. Seu tipo é [CompletableFuture<Void>]: ele não devolve resultado ([Void] é a classe correspondente a [void]; seu único valor é [null]);
  • Linhas 25–28: [completedFuture(42)] devolve um [CompletableFuture] já concluído com o resultado 42, e [failedFuture(exception)] (Java 9) devolve um [CompletableFuture] que já falhou. Eles são usados quando um método precisa devolver um *[CompletableFuture] mas já tem o resultado (um valor em cache, por exemplo) ou já sabe que vai falhar. [resultNow()] e [exceptionNow()] (Java 19) devolvem o resultado ou a exceção de uma operação concluída sem esperar (lançam uma [IllegalStateException]* se a operação não estiver no estado desejado);
  • linhas 31–37: 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] (uma exceção não verificada) cuja causa ([getCause()]) é a exceção original, neste caso uma [NumberFormatException];
  • linhas 40–45: [get()], o método herdado da interface [Future], também espera de forma bloqueante, mas encapsula a exceção em uma [ExecutionException] — uma exceção verificada — e pode lançar também uma [InterruptedException], que também é verificada: a chamada é, portanto, colocada em um *[try / catch], que intercepta a primeira, e o método *[main] declara a segunda (linha 2). [join()] é mais conveniente em código que manipula [CompletableFuture]; [get()] é o único disponível para um simples [Future], e existe uma versão com prazo, [get(timeout, unit)];
  • Linhas 48–50: uma continuação. [f2.thenApply(function)] devolve um novo [CompletableFuture], que será concluído com o resultado da função aplicada ao resultado de [f2] assim que [f2] for concluído. Aqui, a função ignora seu parâmetro ([null]) e devolve 42: o resultado é um [CompletableFuture<Integer>]. [thenAccept] anexa uma função que consome o resultado sem produzir um ([Consumer<T>]) e devolve um [CompletableFuture<Void>]. Se a operação original falha, a continuação não é executada e a falha se propaga ao longo da cadeia;
  • linhas 53–55: os métodos booleanos [isDone()] (concluída, independentemente da maneira), [isCompletedExceptionally()] (concluída com uma exceção ou abortada) e [isCancelled()] (abortada).

Há inúmeros métodos em [CompletableFuture] (mais de cinquenta). A tabela a seguir lista os que usaremos:

Método
Função
[supplyAsync(f)], [runAsync(r)]
Executar uma função (com ou sem resultado) usando um executor
[completedFuture(v)], [failedFuture(e)]
Criar uma operação já concluída, com sucesso ou com falha
[complete(v)], [completeExceptionally(e)]
concluir uma tarefa por conta própria
[thenApply(f)]
Transformar o resultado: [T → U]
[thenAccept(c)], [thenRun(r)]
Usar o resultado ou executar uma ação após a operação
[thenCompose(f)]
Encadear outra operação assíncrona: [T → CompletableFuture<U>]
[thenCombine(other, f)]
Combinar os resultados de duas operações executadas em paralelo
[allOf(...)], [anyOf(...)]
Esperar que todas as operações terminem, ou que a primeira termine
[exceptionally(f)], [handle(f)], [whenComplete(c)]
Tratar ou observar uma falha
[orTimeout(...)], [completeOnTimeout(...)]
limitar a duração de uma operação
[join()], [get()]
Esperar o resultado bloqueando a thread atual

Os métodos [thenXxx], [handle] e [whenComplete] também existem na versão [thenXxxAsync]: discutiremos a diferença na seção “Qual thread executa o restante do código?”

9.3. Métodos assíncronos

9.3.1. Primeira abordagem: devolver um CompletableFuture

Em Java, um método assíncrono é simplesmente um método que inicia uma operação e devolve imediatamente, sem esperar, um [CompletableFuture] que a representa:

  • [CompletableFuture<Void>] se a operação não devolve resultado;
  • [CompletableFuture<T>] se ela devolve um resultado do tipo [T].

A linguagem não impõe nenhuma convenção de nomenclatura. As bibliotecas Java costumam acrescentar o sufixo [Async] ([sendAsync], [supplyAsync]) a esses métodos, mas isso não é uma regra: o tipo de retorno basta para identificá-los.

O programa [Async04.java] prepara café e conta cubos de açúcar:

// métodos que retornam um CompletableFuture: as etapas são compostas com thenRun e thenCompose
final long start = System.nanoTime();

void main() {
    display("call of makeCoffee");
    CompletableFuture<Void> preparation = makeCoffee();
    display("makeCoffee has returned: the program continues");
    display("call of countSugars");
    CompletableFuture<Integer> counting = countSugars(3);
    display("countSugars has returned");
    // combinamos as duas operações e depois esperamos o resultado da combinação
    int nbSugars = preparation.thenCombine(counting, (nothing, count) -> count).join();
    display("coffee ready, with " + nbSugars + " sugar(s)");
}

// uma operação que não retorna resultado: ela retorna um CompletableFuture<Void>
CompletableFuture<Void> makeCoffee() {
    display("  coffee: the machine is heating up");
    // o método descreve a sequência de etapas e retorna imediatamente
    return delay(1000)
            .thenRun(() -> display("  coffee: the machine is pouring the coffee"))
            .thenCompose(nothing -> delay(500))
            .thenRun(() -> display("  coffee: done"));
}

// uma operação que retorna um inteiro: ela retorna um CompletableFuture<Integer>
CompletableFuture<Integer> countSugars(int count) {
    // uma cadeia de etapas que começa com um CompletableFuture já concluído
    CompletableFuture<Void> steps = CompletableFuture.completedFuture(null);
    for (int i = 1; i <= count; i++) {
        // uma lambda só pode usar uma variável local efetivamente final
        int number = i;
        steps = steps.thenCompose(nothing -> delay(200))
                .thenRun(() -> display("  sugar no. " + number));
    }
    // no fim da cadeia, o resultado: o número de açúcares
    return steps.thenApply(nothing -> count);
}

// o equivalente assíncrono de Thread.sleep: um CompletableFuture concluído após [ms] milissegundos
CompletableFuture<Void> delay(long ms) {
    return new CompletableFuture<Void>().completeOnTimeout(null, ms, TimeUnit.MILLISECONDS);
}

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

Resultados:

> java Async04.java
    3 ms : call of makeCoffee
   12 ms :   coffee: the machine is heating up
   15 ms : makeCoffee has returned: the program continues
   16 ms : call of countSugars
   17 ms : countSugars has returned
  217 ms :   sugar no. 1
  417 ms :   sugar no. 2
  618 ms :   sugar no. 3
 1014 ms :   coffee: the machine is pouring the coffee
 1515 ms :   coffee: done
 1516 ms : coffee ready, with 3 sugar(s)

Comentários:

  • Linhas 40–43: o método [delay] é o equivalente assíncrono de [Thread.sleep]: ele devolve um [CompletableFuture<Void>] que será concluído após o tempo limite, sem ocupar uma thread. Vamos usá-lo em muitos exemplos para simular E/S;
  • Linhas 17–24: uma operação sem resultado. O método exibe uma mensagem inicial e depois descreve a sequência de etapas e devolve imediatamente o [CompletableFuture] final: é por isso que a linha 4 dos resultados aparece logo após a linha 3, e não um segundo e meio depois. As etapas serão executadas depois, cada uma assim que a anterior terminar:
    • linha 21: [thenRun(action)] executa uma ação quando a operação anterior termina;
    • linha 22: [thenCompose(function)] dispara outra operação assíncrona: a própria função devolve um [CompletableFuture] (neste caso, um novo atraso de 500 ms), e o [CompletableFuture] devolvido por [thenCompose] só será concluído quando essa segunda operação terminar. Com [thenApply], teríamos obtido um [CompletableFuture<CompletableFuture<Void>>], que teria sido concluído assim que o segundo atraso começasse: [thenCompose] está para [thenApply] assim como [flatMap] está para [map] na API Stream;
  • Linhas 27–38: uma operação que devolve um inteiro. Um laço não pode “esperar” a cada iteração: ele constrói a sequência de etapas, com cada iteração acrescentando um atraso e uma exibição à sequência existente, partindo de um [CompletableFuture] pré-calculado (linha 29). A cadeia inteira é construída em alguns microssegundos e depois se desenrola à medida que os atrasos ocorrem. A variável [number] (linha 32) é necessária porque uma lambda só pode usar uma variável local efetivamente final, o que [i] não é. Por fim, [thenApply] converte a cadeia em um [CompletableFuture<Integer>], cujo resultado é o número de açúcares;
  • Linhas 6–10: o programa principal chama os dois métodos. Ele obtém dois valores [CompletableFuture] e continua a execução. As duas operações prosseguem então “simultaneamente”: os açúcares são contados (linhas 7–9 dos resultados) enquanto a máquina esquenta;
  • linha 12: [preparation.thenCombine(counting, function)] devolve um [CompletableFuture] concluído quando ambas as operações terminam, junto com o resultado da função aplicada aos dois resultados: neste caso, retém-se o número de cubos de açúcar. [join()] espera esse resultado. O café fica pronto após 1,5 segundo — a duração da mais longa das duas operações — e não após 2,1 segundos (1,5 + 3 × 0,2).

Vemos os pontos fortes e as limitações dessa abordagem. Nenhuma thread espera: as etapas são executadas pela thread do timer à medida que os intervalos de tempo transcorrem. Mas o código deixa de se ler como uma sequência de instruções: o laço de [countSugars] não faz o que um laço costuma fazer (ele constrói uma cadeia em vez de executar iterações), e um simples [if] ou [try / catch] no meio das etapas exige métodos dedicados. Esse é o preço a pagar quando a linguagem não oferece palavras-chave como [await].

9.3.2. Segunda abordagem: código bloqueante em threads virtuais

As threads virtuais permitem escrever os mesmos métodos como métodos comuns, bloqueantes. O programa [Async05.java] prepara a mesma xícara de café:

// o mesmo café com threads virtuais: métodos comuns, bloqueantes, que se leem de cima para baixo
final long start = System.nanoTime();

void main() throws InterruptedException, ExecutionException {
    // um executor que cria uma thread virtual para cada tarefa que lhe é dada
    try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
        display("start of makeCoffee");
        Future<?> preparation = executor.submit(this::makeCoffee);
        display("makeCoffee is started: the program continues");
        display("start of countSugars");
        Future<Integer> counting = executor.submit(() -> countSugars(3));
        display("countSugars is started");
        // agora esperamos os dois resultados
        preparation.get();
        int nbSugars = counting.get();
        display("coffee ready, with " + nbSugars + " sugar(s)");
    }
}

// um método comum que não retorna resultado
void makeCoffee() {
    display("  coffee: the machine is heating up");
    // uma espera bloqueante: em uma thread virtual, ela libera a thread carrier
    sleep(1000);
    display("  coffee: the machine is pouring the coffee");
    sleep(500);
    display("  coffee: done");
}

// um método comum que retorna um inteiro
int countSugars(int count) {
    for (int i = 1; i <= count; i++) {
        sleep(200);
        display("  sugar no. " + i);
    }
    return count;
}

// Thread.sleep sem exceção verificada: uma interrupção vira uma CancellationException
void sleep(long ms) {
    try {
        Thread.sleep(ms);
    } catch (InterruptedException e) {
        // restauramos o flag de interrupção da thread antes de lançar a exceção
        Thread.currentThread().interrupt();
        throw new CancellationException("wait interrupted");
    }
}

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

Resultados:

> java Async05.java
    3 ms : start of makeCoffee
   17 ms :   coffee: the machine is heating up
   18 ms : makeCoffee is started: the program continues
   18 ms : start of countSugars
   19 ms : countSugars is started
  221 ms :   sugar no. 1
  422 ms :   sugar no. 2
  623 ms :   sugar no. 3
 1020 ms :   coffee: the machine is pouring the coffee
 1521 ms :   coffee: done
 1522 ms : coffee ready, with 3 sugar(s)

Comentários:

  • Linhas 20–37: as duas operações são métodos comuns: [makeCoffee] não devolve nada ([void]), e [countSugars] devolve um [int]. As chamadas são operações [Thread.sleep] bloqueantes; o laço é um laço de verdade. Nada nesses métodos indica que serão executados de forma concorrente: eles poderiam ser chamados diretamente;
  • linhas 39–48: o método [sleep] chama [Thread.sleep] e converte qualquer [InterruptedException] (exceção verificada) em uma [CancellationException] (exceção não verificada), depois de restaurar o indicador de interrupção da thread: essa é a regra ao interceptar uma [InterruptedException] sem propagá-la (voltaremos a isso na seção sobre cancelamento);
  • linha 6: um executor que cria uma thread virtual para cada tarefa. Ele é declarado em um [try] com recurso: seu método [close()] esperará que todas as tarefas terminem;
  • Linhas 8 e 11: [submit] delega cada método a uma nova thread virtual e devolve um [Future]. A referência de método [this::makeCoffee] é um [Runnable] (o método não devolve nada), resultando em um [Future<?>]; a lambda [() -> countSugars(3)] é um [Callable<Integer>], resultando em um [Future<Integer>];
  • Linhas 14–15: o programa principal espera os dois resultados com [get()]. É uma espera bloqueante da thread principal, o que não tem consequência aqui;
  • os resultados são os mesmos de [Async04.java]: 1,5 segundo no total, com o açúcar sendo contado enquanto a máquina esquenta. Durante as esperas, nenhuma thread de sistema fica bloqueada: as duas threads virtuais são separadas de suas threads portadoras.

Com as threads virtuais, a assincronia deixa de ser uma questão de escrita do código e passa a ser de execução: escrevemos código bloqueante, e é a escolha do executor (threads virtuais em vez de um pool de threads de plataforma) que determina se as esperas bloqueiam threads de sistema. É por isso que as bibliotecas Java existentes (JDBC, arquivos, sockets, [HttpClient.send]…), todas escritas de forma bloqueante, aproveitam as threads virtuais sem modificação.

9.3.3. O que a JVM faz

Como uma thread virtual pode ser interrompida no meio de um laço, liberar sua thread hospedeira e depois retomar mais tarde no mesmo ponto, com os mesmos valores de variáveis locais, possivelmente em outra thread hospedeira? Uma thread virtual é um objeto Java ([java.lang.VirtualThread], uma classe derivada de [Thread]) que possui sua própria pilha de chamadas. Para executá-la, a JVM a “monta” em uma thread portadora — uma thread de plataforma de um [ForkJoinPool] reservado para esse fim, que por padrão tem tantas threads quanto processadores. Quando a thread virtual chama uma operação bloqueante ([Thread.sleep], leitura de um socket; [BlockingQueue.take], espera por um lock…), as classes da JVM — reescritas para esse fim no Java 21 — não bloqueiam a thread hospedeira:

  • elas registram a operação no sistema (um timer para um atraso, o mecanismo de notificação de E/S do sistema — [epoll] no Linux — para um socket);
  • elas “desmontam” a thread virtual: os quadros de sua pilha de chamadas são copiados para o heap como um objeto chamado continuação, e a thread portadora é devolvida ao [ForkJoinPool], que lhe atribui outra thread virtual pronta para executar;
  • quando a operação termina, a thread virtual volta a ficar pronta: ela será remontada na primeira thread portadora disponível, os quadros de sua pilha serão copiados de volta e a execução será retomada imediatamente após a chamada bloqueante.

Esse é o princípio dos métodos de callback (“me chame de volta quando a operação terminar”), mas é a JVM que fragmenta a execução, salva as variáveis e restaura o contexto no nível da pilha de chamadas, sem que o código-fonte mostre qualquer vestígio disso. Outras linguagens confiam essa tarefa ao compilador, que transforma cada método [async] em uma “máquina de estados”; Java a confia à JVM, o que lhe permite tratar da mesma forma todo o código existente.

Há duas limitações a serem observadas:

  • certas operações não conseguem desanexar a thread virtual; ela permanece, portanto, "fixada" (pinned) à sua thread hospedeira, que fica bloqueada durante a espera. Isso ocorre durante a execução de um método nativo e durante a maior parte das leituras e escritas em arquivos (o sistema não fornece uma notificação para arquivos que possa ser usada pela JVM); nesse último caso, o [ForkJoinPool] compensa criando temporariamente uma thread portadora adicional. Até o Java 23, isso também valia para uma thread virtual que esperava dentro de um bloco [synchronized]; desde o Java 24, isso não ocorre mais;
  • uma thread virtual não acelera um cálculo: uma thread virtual que realiza um cálculo ocupa sua thread hospedeira durante toda a duração do cálculo. As threads virtuais se destinam a programas que esperam muito, não àqueles que calculam muito (para estes, há os pools de threads e os streams paralelos do capítulo anterior).

9.3.4. Qual thread executa o trecho seguinte?

O programa [Async06.java] exibe a thread que executa cada trecho de código:

// qual thread executa o restante de um processamento?
void main() throws InterruptedException {
    display("start of the program, parallelism of the common pool: " + ForkJoinPool.getCommonPoolParallelism());

    // 1 - a continuação de um CompletableFuture já concluído é executada imediatamente, pelo chamador
    CompletableFuture.completedFuture(42).thenAccept(value -> display("1 - thenAccept, result known"));

    // 2 - caso contrário, ela é executada pela thread que conclui o CompletableFuture
    delay(100).thenRun(() -> display("2 - thenRun after a delay")).join();
    CompletableFuture<String> order = new CompletableFuture<>();
    order.thenAccept(text -> display("2 - thenAccept after complete(\"" + text + "\")"));
    Thread.ofPlatform().name("deliverer").start(() -> order.complete("delivered")).join();

    // 3 - as variantes xxxAsync entregam a continuação a um executor
    delay(100).thenRunAsync(() -> display("3 - thenRunAsync, default executor")).join();
    ThreadFactory factory = Thread.ofPlatform().name("pool-", 1).factory();
    try (ExecutorService pool = Executors.newFixedThreadPool(2, factory)) {
        delay(100).thenRunAsync(() -> display("3 - thenRunAsync, chosen executor"), pool).join();
        CompletableFuture.runAsync(() -> display("3 - runAsync, chosen executor"), pool).join();
    }
    try (ExecutorService virtuals = Executors.newVirtualThreadPerTaskExecutor()) {
        CompletableFuture.runAsync(() -> display("3 - runAsync, virtual threads"), virtuals).join();
    }

    // 4 - uma thread virtual pode trocar de thread carrier após cada espera
    Thread a = Thread.ofVirtual().start(() -> work("A"));
    Thread b = Thread.ofVirtual().start(() -> work("B"));
    a.join();
    b.join();
    display("end of the program");
}

void work(String name) {
    for (int i = 1; i <= 3; i++) {
        display("  " + name + i + " : before the wait");
        sleep(100);
    }
}

// um CompletableFuture concluído após [ms] milissegundos
CompletableFuture<Void> delay(long ms) {
    return new CompletableFuture<Void>().completeOnTimeout(null, ms, TimeUnit.MILLISECONDS);
}

// Thread.sleep sem exceção verificada: uma interrupção vira uma CancellationException
void sleep(long ms) {
    try {
        Thread.sleep(ms);
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        throw new CancellationException("wait interrupted");
    }
}

// exibição prefixada pela thread que a executa
// (nome de uma thread de plataforma, descrição de uma thread virtual)
void display(String message) {
    Thread thread = Thread.currentThread();
    IO.println("[" + (thread.isVirtual() ? thread.toString() : thread.getName()) + "] " + message);
}

Resultados:

> java Async06.java
[main] start of the program, parallelism of the common pool: 1
[main] 1 - thenAccept, result known
[ForkJoinPool.commonPool-delayScheduler] 2 - thenRun after a delay
[deliverer] 2 - thenAccept after complete("delivered")
[ForkJoinPool.commonPool-worker-1] 3 - thenRunAsync, default executor
[pool-1] 3 - thenRunAsync, chosen executor
[pool-2] 3 - runAsync, chosen executor
[VirtualThread[#28]/runnable@ForkJoinPool-1-worker-1] 3 - runAsync, virtual threads
[VirtualThread[#31]/runnable@ForkJoinPool-1-worker-1]   A1 : before the wait
[VirtualThread[#32]/runnable@ForkJoinPool-1-worker-2]   B1 : before the wait
[VirtualThread[#32]/runnable@ForkJoinPool-1-worker-2]   B2 : before the wait
[VirtualThread[#31]/runnable@ForkJoinPool-1-worker-1]   A2 : before the wait
[VirtualThread[#31]/runnable@ForkJoinPool-1-worker-2]   A3 : before the wait
[VirtualThread[#32]/runnable@ForkJoinPool-1-worker-1]   B3 : before the wait
[main] end of the program

Comentários:

  • linha 3: o pool compartilhado ([ForkJoinPool.commonPool()]), o executor padrão de [CompletableFuture], tem um paralelismo igual ao número de processadores menos um, ou seja, 1 em nossa máquina de 2 processadores (linha 2 dos resultados);
  • Linha 6: a continuação de um [CompletableFuture] que já foi concluído é executada imediatamente pela thread que a anexou: a thread [main] (linha 3);
  • linhas 9–12: se a operação não estiver concluída, a continuação será executada pela thread que a concluir: a thread do timer de timeout para [delay(100)] (linha 4), a thread [deliverer], que chama [complete] para o pedido (linha 5). Portanto, a thread que executa uma continuação não assíncrona não é escolhida; isso é irrelevante para uma ação breve, mas uma continuação longa ou bloqueante imobilizaria essa thread (a thread do timer, por exemplo, que cuida de todos os timeouts de [CompletableFuture]);
  • linhas 15–23: as variantes [xxxAsync] ([thenRunAsync], [thenApplyAsync]…) delegam a continuação a um executor: sem parâmetros adicionais, ao pool compartilhado (linha 6 dos resultados); com um executor como último parâmetro, a esse executor. Isso permite escolher threads de plataforma (linhas 7–8: um pool de duas threads cujos nomes são definidos por uma fábrica de threads, [ThreadFactory], construída por [Thread.ofPlatform().name("pool-", 1).factory()]) ou threads virtuais (linha 9). [supplyAsync] e [runAsync] também aceitam um executor;
  • Linhas 26–38: duas threads virtuais que exibem uma mensagem e depois dormem, três vezes seguidas. Os resultados mostram que elas não permanecem anexadas a uma única thread hospedeira: a thread virtual nº 31 (A) começa em [worker-1] e termina em [worker-2], enquanto a nº 32 (B) faz o oposto. Enquanto uma dorme, sua thread portadora fica livre para a outra. Portanto, em uma thread virtual, nunca se deve supor que o código que segue uma espera seja executado pela mesma thread portadora que o código que a precede; mas é sempre a mesma thread virtual, e é isso que importa para o programa ([Thread.currentThread()] retorna a thread virtual; suas variáveis, [ThreadLocal], são preservadas).

Esse modo de realizar várias operações simultaneamente sem aumentar o número de threads do sistema chama-se concorrência. Ele difere do paralelismo, que consiste em executar vários cálculos ao mesmo tempo em vários processadores (como visto no capítulo anterior: pools de threads, streams paralelos). A assincronia facilita a concorrência de E/S; ela não torna os cálculos mais rápidos.

A escolha do executor é, portanto, importante:

  • o pool compartilhado é adequado para continuações breves e cálculos curtos; operações bloqueantes não devem ser executadas nele, pois isso gera o risco de inanição (starvation) descrito em [Async01.java] (ele tem apenas uma thread em nossa máquina);
  • para uma operação bloqueante (E/S, chamadas JDBC ou [Thread.sleep]), use um executor de threads virtuais: [CompletableFuture.supplyAsync(supplier, virtualExecutor)];
  • para uma interface gráfica, passamos um executor que faz a continuação ser executada pela thread da interface, o que permite atualizar os componentes gráficos: com Swing, [thenAcceptAsync(action, SwingUtilities::invokeLater)] (a referência de método [SwingUtilities::invokeLater] é um [Executor] válido, pois [Executor] é uma interface funcional cujo único método recebe um [Runnable]); com JavaFX, [Platform::runLater].

9.3.5. O programa principal

Em outras linguagens, o método principal de um programa assíncrono deve ser declarado de uma forma específica. Em Java, não há essa exigência: o método [main] é executado pela thread de plataforma [main], e cabe a esse método esperar a conclusão das operações que iniciou, usando [join()] ou [get()]. Este é o único lugar em que uma espera bloqueante sobre um [CompletableFuture] é normal. O programa [Async07.java] realiza uma contagem regressiva assíncrona:

// o programa principal espera o fim das operações assíncronas e define o código de saída
void main(String[] args) {
    // o número de segundos é passado como argumento
    if (args.length != 1 || !args[0].matches("\\d+")) {
        IO.println("syntax: java Async07.java nbSeconds");
        // o código de saída do programa: 0 para sucesso, outro valor para erro
        System.exit(1);
    }
    CompletableFuture<Void> countdown = countDown(Integer.parseInt(args[0]));
    IO.println("countdown started");
    // sem esta espera, main terminaria imediatamente e o programa com ele
    countdown.join();
    IO.println("finished");
}

// um laço assíncrono é escrito com recursão: cada etapa inicia a seguinte
CompletableFuture<Void> countDown(int nbSeconds) {
    if (nbSeconds == 0) {
        return CompletableFuture.completedFuture(null);
    }
    IO.println("still " + nbSeconds + " s");
    return delay(1000).thenCompose(nothing -> countDown(nbSeconds - 1));
}

// um CompletableFuture concluído após [ms] milissegundos
CompletableFuture<Void> delay(long ms) {
    return new CompletableFuture<Void>().completeOnTimeout(null, ms, TimeUnit.MILLISECONDS);
}

Resultados, primeiro com e depois sem argumento:

1
2
3
4
5
6
> java Async07.java 3
still 3 s
countdown started
still 2 s
still 1 s
finished
1
2
3
4
> java Async07.java
syntax: java Async07.java nbSeconds
> echo $?
1

Comentários:

  • linha 2: o parâmetro [args] de [main] recebe os argumentos da linha de comando, que são colocados após o nome do arquivo: [java Async07.java 3];
  • Linhas 4–8: se o argumento estiver ausente ou não for um inteiro positivo (expressão regular [\d+]: um ou mais dígitos), o programa termina com [System.exit(1)]. O inteiro passado para [System.exit] é 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 $?] no Linux (segundo resultado), [echo %ERRORLEVEL%] no Windows. Um programa cujo método [main] termina normalmente retorna o código 0;
  • linhas 16–23: uma contagem regressiva assíncrona. Um laço assíncrono é naturalmente implementado por meio de recursão: cada etapa exibe uma mensagem e depois, usando [thenCompose], introduz um atraso de um segundo seguido da etapa seguinte. Não há pilha de chamadas: a chamada recursiva é feita por meio da continuação, um segundo depois;
  • linhas 9–12: o método [countDown] exibe sua primeira mensagem e depois devolve o controle (linhas 2–3 dos resultados); o programa principal espera o fim da operação com [join()]. Sem essa espera, [main] terminaria imediatamente, e o programa junto com ele: a JVM para quando restam apenas threads daemon e as threads do timer e do pool compartilhado são daemons. O mesmo vale para as threads virtuais, que são sempre daemons: um programa deve esperar o fim das threads virtuais que iniciou (usando [join], [get], ou o método [close] do executor delas).

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

9.4.1. allOf e invokeAll

O exemplo do café demonstrou isso: o momento em que uma operação assíncrona é iniciada e o momento em que ela é aguardada podem ser diferentes. Escrever [method().join()] inicia a operação e a aguarda imediatamente; escrever [var f = method();] e, depois, [f.join();] permite lançar outras operações nesse intervalo. O programa [Async08.java] compara as duas abordagens usando operações que levam um segundo:

// execução sequencial e execução concorrente de operações de um segundo
long start = System.nanoTime();

void main() throws InterruptedException {
    // 1 - em sequência: cada operação é aguardada antes de iniciar a seguinte
    int a = readTemperature("Angers").join();
    int b = readTemperature("Brest").join();
    int c = readTemperature("Colmar").join();
    IO.println("in sequence: " + a + ", " + b + ", " + c + " in " + elapsed() + " ms");

    // 2 - de forma concorrente: iniciamos as três operações e depois esperamos por elas
    start = System.nanoTime();
    CompletableFuture<Integer> fa = readTemperature("Angers");
    CompletableFuture<Integer> fb = readTemperature("Brest");
    CompletableFuture<Integer> fc = readTemperature("Colmar");
    CompletableFuture.allOf(fa, fb, fc).join();
    IO.println("concurrently: " + fa.resultNow() + ", " + fb.resultNow() + ", " + fc.resultNow()
            + " in " + elapsed() + " ms");

    // 3 - allOf sobre uma lista de CompletableFutures e depois a lista dos resultados
    start = System.nanoTime();
    List<String> cities = List.of("Angers", "Brest", "Colmar", "Dijon", "Évry", "Foix");
    List<CompletableFuture<Integer>> readings = cities.stream().map(this::readTemperature).toList();
    List<Integer> temperatures = CompletableFuture.allOf(readings.toArray(CompletableFuture[]::new))
            .thenApply(nothing -> readings.stream().map(CompletableFuture::join).toList())
            .join();
    IO.println(cities.size() + " cities: " + temperatures + " in " + elapsed() + " ms");

    // 4 - a mesma coisa com threads virtuais e um método bloqueante
    start = System.nanoTime();
    try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
        List<Callable<Integer>> tasks = cities.stream()
                .map(city -> (Callable<Integer>) () -> readTemperatureBlocking(city))
                .toList();
        // invokeAll inicia todas as tarefas e retorna seus Futures quando todas terminaram
        List<Integer> results = executor.invokeAll(tasks).stream().map(Future::resultNow).toList();
        IO.println(cities.size() + " cities (virtual threads): " + results + " in " + elapsed() + " ms");
    }
}

// simula a consulta a um serviço remoto que responde em um segundo
CompletableFuture<Integer> readTemperature(String city) {
    // uma "temperatura" derivada do nome da cidade
    return delay(1000).thenApply(nothing -> 10 + city.length());
}

// a mesma operação, escrita de forma bloqueante
int readTemperatureBlocking(String city) throws InterruptedException {
    Thread.sleep(1000);
    return 10 + city.length();
}

// um CompletableFuture concluído após [ms] milissegundos
CompletableFuture<Void> delay(long ms) {
    return new CompletableFuture<Void>().completeOnTimeout(null, ms, TimeUnit.MILLISECONDS);
}

// milissegundos decorridos desde [start]
long elapsed() {
    return (System.nanoTime() - start) / 1_000_000;
}

Resultados:

1
2
3
4
5
> java Async08.java
in sequence: 16, 15, 16 in 3007 ms
concurrently: 16, 15, 16 in 1000 ms
6 cities: [16, 15, 16, 15, 14, 14] in 1006 ms
6 cities (virtual threads): [16, 15, 16, 15, 14, 14] in 1013 ms

Comentários:

  • linhas 41–45: a operação simulada: um atraso de um segundo, seguido de uma "temperatura" derivada do comprimento do nome da cidade;
  • linhas 6–8: cada operação é iniciada e depois aguardada antes de iniciar a seguinte. As três operações são realizadas uma após a outra: 3 segundos (linha 2 dos resultados). Esta é a abordagem correta quando uma operação precisa do resultado da anterior (caso em que, em vez disso, se escreveria uma cadeia de [thenCompose]);
  • linhas 13–15: as três operações são iniciadas sem esperar umas pelas outras. Elas são executadas simultaneamente;
  • linha 16: [CompletableFuture.allOf(...)] retorna um [CompletableFuture<Void>], que é concluído quando todas as operações passadas a ele terminam. Esperamos por ele com [join()]: 1 segundo em vez de 3 (linha 3);
  • linhas 17–18: as três operações estão concluídas, portanto [resultNow()] retorna seus resultados imediatamente;
  • linhas 22–27: o caso de uma lista de operações. [allOf] espera um array ([CompletableFuture<?>...]): o método [toArray(CompletableFuture[]::new)] da lista o cria. [allOf] não retorna os resultados: eles são coletados em uma continuação chamando [join()] em cada operação, o que não bloqueia, pois todas já foram concluídas. A lista de resultados é obtida na ordem das operações (não na ordem em que foram concluídas). A expressão [cities.stream().map(this::readTemperature).toList()] chama o método para cada cidade, lançando assim seis operações simultaneamente; as seis juntas levam um segundo (linha 4);
  • linhas 29–38: a mesma coisa com um método bloqueante (linhas 47–51) executado por threads virtuais. O método [invokeAll] de um executor recebe uma coleção de [Callable<T>], lança todos eles e retorna a lista de seus [Future<T>] quando todos estiverem concluídos: este é o equivalente bloqueante de *[allOf]. O cast de tipo [(Callable<Integer>)] na linha 33 informa ao compilador o tipo da lambda, que ele não consegue inferir sozinho em um [map]*. As seis operações juntas levam um segundo (linha 5).

9.4.2. anyOf

[CompletableFuture.anyOf(...)] retorna um [CompletableFuture<Object>] que termina assim que uma das operações passadas a ele for concluída, com o resultado (ou a exceção) dessa operação. O programa [Async09.java] o usa de duas maneiras:

// anyOf: reagir à primeira operação concluída
long start = System.nanoTime();

void main() {
    // 1 - consultamos três servidores espelho e ficamos com a primeira resposta
    List<CompletableFuture<String>> requests = List.of(
            query("mirror-paris", 800),
            query("mirror-lyon", 300),
            query("mirror-lille", 600));
    // anyOf retorna um CompletableFuture<Object> que é concluído como a primeira operação concluída
    Object first = CompletableFuture.anyOf(requests.toArray(CompletableFuture[]::new)).join();
    display("first answer: " + first);
    // as outras requisições continuam: esperamos por elas aqui para ver suas respostas
    CompletableFuture.allOf(requests.toArray(CompletableFuture[]::new)).join();
    display("all the answers: " + requests.stream().map(CompletableFuture::resultNow).toList());

    // 2 - uma operação com tempo limitado: fazemos uma "corrida" dela contra um atraso
    start = System.nanoTime();
    CompletableFuture<String> slow = query("slow-server", 2000);
    CompletableFuture<Object> race = CompletableFuture.anyOf(slow, delay(500));
    race.join();
    if (slow.isDone()) {
        display("answer obtained in time: " + slow.join());
    } else {
        display("the slow server did not answer within the 500 ms delay");
    }
}

// simula um servidor que responde após [duration] milissegundos
CompletableFuture<String> query(String server, int duration) {
    return delay(duration).thenApply(nothing -> server + " (" + duration + " ms)");
}

// um CompletableFuture concluído após [ms] milissegundos
CompletableFuture<Void> delay(long ms) {
    return new CompletableFuture<Void>().completeOnTimeout(null, ms, TimeUnit.MILLISECONDS);
}

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

Resultados:

1
2
3
4
> java Async09.java
  309 ms : first answer: mirror-lyon (300 ms)
  806 ms : all the answers: [mirror-paris (800 ms), mirror-lyon (300 ms), mirror-lille (600 ms)]
  500 ms : the slow server did not answer within the 500 ms delay

Comentários:

  • linhas 6–9: três servidores espelho são consultados; todos têm as mesmas informações e respondem em velocidades variadas. As três operações são armazenadas em uma lista;
  • linha 11: [anyOf] retorna um [CompletableFuture<Object>], cujo resultado é o da primeira operação concluída. Seu tipo é [Object] porque as operações passadas a [anyOf] podem ter tipos de resultado diferentes: seria necessário fazer um cast para usá-lo como string. A primeira resposta chega após 300 ms (linha 2 dos resultados);
  • linha 14: as outras requisições não são encerradas por [anyOf]; elas continuam até terminar. Aqui, esperamos que todas exibam suas respostas (linha 3);
  • linhas 19–26: um uso comum de [anyOf]: limitar a duração de uma espera estabelecendo uma "corrida" entre a operação e um timeout. Se a operação não tiver terminado quando a corrida acabar, o timeout venceu: a operação demorou demais (linha 4). [CompletableFuture] oferece uma maneira mais direta de escrever esse caso, o método [orTimeout], apresentado mais adiante.

9.4.3. Processando os resultados à medida que chegam

Muitas vezes queremos processar os resultados de várias operações à medida que são concluídas, sem esperar a mais lenta. Com [CompletableFuture], isso é simples: basta anexar uma continuação a cada operação. Para tarefas submetidas a um executor, a classe [ExecutorCompletionService] (Java 5) retorna os objetos [Future] na ordem em que as tarefas são concluídas. O programa [Async10.java] processa cinco "arquivos", cada um dos quais leva entre 100 e 900 ms para ser processado, das duas maneiras:

// processamento dos resultados na ordem em que as operações terminam
long start = System.nanoTime();
final int[] durations = {900, 300, 700, 100, 500};

void main() throws InterruptedException, ExecutionException {
    // 1 - com CompletableFutures: uma continuação por operação, executada assim que ela termina
    List<CompletableFuture<Void>> displays = new ArrayList<>();
    for (int i = 0; i < durations.length; i++) {
        displays.add(process("file" + i + ".txt", durations[i]).thenAccept(this::display));
    }
    CompletableFuture.allOf(displays.toArray(CompletableFuture[]::new)).join();
    display("1 - all the files have been processed");

    // 2 - com threads virtuais: um CompletionService entrega os Futures na ordem em que terminam
    start = System.nanoTime();
    try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
        CompletionService<String> service = new ExecutorCompletionService<>(executor);
        for (int i = 0; i < durations.length; i++) {
            String file = "file" + i + ".txt";
            int duration = durations[i];
            service.submit(() -> processBlocking(file, duration));
        }
        // take() espera (de forma bloqueante) a próxima tarefa concluída
        for (int i = 0; i < durations.length; i++) {
            display(service.take().get());
        }
    }
    display("2 - all the files have been processed");
}

// simula o processamento de um arquivo que dura [duration] milissegundos
CompletableFuture<String> process(String file, int duration) {
    return new CompletableFuture<String>()
            .completeOnTimeout(file + " processed in " + duration + " ms", duration, TimeUnit.MILLISECONDS);
}

// o mesmo processamento, escrito de forma bloqueante
String processBlocking(String file, int duration) throws InterruptedException {
    Thread.sleep(duration);
    return file + " processed in " + duration + " ms";
}

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

Resultados:

> java Async10.java
  107 ms : file3.txt processed in 100 ms
  318 ms : file1.txt processed in 300 ms
  508 ms : file4.txt processed in 500 ms
  707 ms : file2.txt processed in 700 ms
  906 ms : file0.txt processed in 900 ms
  907 ms : 1 - all the files have been processed
  115 ms : file3.txt processed in 100 ms
  314 ms : file1.txt processed in 300 ms
  514 ms : file4.txt processed in 500 ms
  714 ms : file2.txt processed in 700 ms
  914 ms : file0.txt processed in 900 ms
  915 ms : 2 - all the files have been processed

Comentários:

  • Linhas 7–11: cada tarefa de processamento recebe sua própria continuação, [thenAccept(this::display)], que é executada assim que ela termina: o arquivo 3 (100 ms) é exibido primeiro, o arquivo 0 (900 ms) por último (linhas 2–6 dos resultados). O método [process] (linhas 31–35) retorna um [CompletableFuture<String>] concluído após a duração especificada com a mensagem desejada ([completeOnTimeout] recebe diretamente o valor do resultado). A lista de continuações é usada para esperar o fim de todas as exibições com [allOf];
  • linhas 16–27: um [CompletionService<T>] encapsula um executor (neste caso, um executor de threads virtuais). Seu método [submit] lança uma tarefa; seu método [take()] espera, de forma bloqueante, a próxima tarefa concluída e retorna seu [Future], cujo resultado é retornado imediatamente por [get()]. O laço das linhas 24–26 processa, portanto, os arquivos na ordem em que são concluídos (linhas 8–12);
  • em ambos os casos, o processo inteiro leva 900 ms — a duração do processamento mais longo — e cada resultado é exibido o mais cedo possível.

9.5. Exceções em código assíncrono

9.5.1. Propagação, exceptionally, handle, whenComplete

Uma exceção lançada por uma operação assíncrona não é relançada ao código que iniciou a operação: ela é armazenada no [CompletableFuture], que passa ao estado [FAILED]. Ela se propaga então ao longo da cadeia de continuações até chegar a um método que a trate, ou até chegar a [join()], que a relança encapsulada em uma [CompletionException]. O programa [Async11.java] examina os vários casos:

// exceções em código assíncrono
void main() {
    // 1 - join() lança uma CompletionException que encapsula a exceção da operação
    try {
        int value = readValue("twelve").join();
        IO.println("value = " + value);
    } catch (CompletionException e) {
        IO.println("1 - join() throws " + name(e) + ", with cause " + name(e.getCause())
                + " : " + e.getCause().getMessage());
    }

    // 2 - exceptionally fornece um valor de substituição em caso de falha
    int value = readValue("thirteen").exceptionally(e -> -1).join();
    IO.println("2 - exceptionally: replacement value " + value);

    // 3 - handle recebe o resultado ou a exceção; whenComplete os observa sem alterar nada
    for (String text : List.of("14", "fifteen")) {
        String outcome = readValue(text)
                .whenComplete((v, e) -> IO.println("3 - whenComplete saw: " + (e == null ? v : name(e))))
                .handle((v, e) -> e == null ? "value " + v : "failure, " + name(cause(e)))
                .join();
        IO.println("3 - handle returned: " + outcome);
    }

    // 4 - um método que retorna um CompletableFuture também pode lançar uma exceção logo na chamada
    try {
        readValue(" ");
        IO.println("4 - the call threw nothing");
    } catch (IllegalArgumentException e) {
        IO.println("4 - it is the call itself that throws " + name(e) + " : " + e.getMessage());
    }

    // 5 - allOf com várias operações que falham
    List<CompletableFuture<Integer>> readings = Stream.of("1", "two", "3", "four")
            .map(this::readValue)
            .toList();
    try {
        CompletableFuture.allOf(readings.toArray(CompletableFuture[]::new)).join();
    } catch (CompletionException e) {
        // join() relança apenas uma das exceções…
        IO.println("5 - allOf fails with " + name(e.getCause()) + " : " + e.getCause().getMessage());
        // … mas cada operação guardou sua exceção ou seu resultado
        for (CompletableFuture<Integer> reading : readings) {
            switch (reading.state()) {
                case SUCCESS -> IO.println("      success, result = " + reading.resultNow());
                case FAILED -> IO.println("      failure, " + name(reading.exceptionNow())
                        + " : " + reading.exceptionNow().getMessage());
                default -> IO.println("      unexpected state: " + reading.state());
            }
        }
    }
}

// uma operação assíncrona que falha se a string não for um inteiro
CompletableFuture<Integer> readValue(String text) {
    // verificação imediata do parâmetro, antes de iniciar a operação
    if (text == null || text.isBlank()) {
        throw new IllegalArgumentException("the text must not be empty");
    }
    // a leitura leva um pouco de tempo
    return new CompletableFuture<Void>()
            .completeOnTimeout(null, 100, TimeUnit.MILLISECONDS)
            .thenApply(nothing -> Integer.parseInt(text));
}

// as continuações costumam receber uma CompletionException: voltamos à sua causa
Throwable cause(Throwable e) {
    return e instanceof CompletionException && e.getCause() != null ? e.getCause() : e;
}

// o nome simples da classe de uma exceção
String name(Throwable e) {
    return e.getClass().getSimpleName();
}

Resultados:

> java Async11.java
1 - join() throws CompletionException, with cause NumberFormatException : For input string: "twelve"
2 - exceptionally: replacement value -1
3 - whenComplete saw: 14
3 - handle returned: value 14
3 - whenComplete saw: CompletionException
3 - handle returned: failure, NumberFormatException
4 - it is the call itself that throws IllegalArgumentException : the text must not be empty
5 - allOf fails with NumberFormatException : For input string: "two"
      success, result = 1
      failure, NumberFormatException : For input string: "two"
      success, result = 3
      failure, NumberFormatException : For input string: "four"

Comentários:

  • Linhas 54–64: o método testado. Ele primeiro verifica seu parâmetro e lança uma [IllegalArgumentException] se a string for [null] ou vazia. Caso contrário, retorna uma operação que espera 100 ms e depois converte a string inteira, o que lança uma [NumberFormatException] se a string não for um número;
  • linhas 4–10: o caso padrão. A exceção lançada por [Integer.parseInt] na continuação da linha 63 é capturada pelo [CompletableFuture]; [join()] relança a exceção encapsulada em uma [CompletionException], da qual [getCause()] retorna a exceção original (linha 2 dos resultados);
  • linha 13: [exceptionally(function)] retorna um [CompletableFuture] que tem o mesmo resultado da operação se ela for bem-sucedida e, caso contrário, o resultado da função aplicada à exceção: este é o [catch] do mundo de [CompletableFuture]. Aqui, uma falha é substituída pelo valor -1 (linha 3);
  • linhas 17–23: dois outros métodos, aplicados a uma operação bem-sucedida e depois a uma operação com falha:
    • [whenComplete(action)] recebe o resultado e a exceção (um dos dois é [null]) e não altera nada: o [CompletableFuture] que ele retorna tem o mesmo resultado ou a mesma exceção da operação. Serve para observação (log, liberação de um recurso): este é o [finally] do mundo de [CompletableFuture];
    • [handle(function)] também recebe o resultado e a exceção, e retorna um novo valor nos dois casos: ele transforma tanto um sucesso quanto uma falha em um resultado;
    • As linhas 6 e 7 dos resultados revelam uma armadilha: a exceção recebida pelas continuações não é [NumberFormatException] mas uma [CompletionException] que a encapsula, porque a falha ocorreu em uma etapa anterior da cadeia (a continuação da linha 63). O método [cause] (linhas 66–69) remonta à exceção original: adquiriremos o hábito de escrevê-lo;
  • linhas 26–31: uma diferença importante em relação aos métodos [async] de outras linguagens: um método que retorna um [CompletableFuture] é um método comum, que pode lançar uma exceção assim que é chamado, antes de criar qualquer [CompletableFuture]. É o que acontece aqui com uma string vazia (linha 8 dos resultados). O código chamador deve, portanto, esperar os dois tipos de erro, ou o método deve retornar uma operação que já falhou ([return CompletableFuture.failedFuture(new IllegalArgumentException(...));]), o que costuma ser preferível;
  • linhas 34–38: esperamos com [allOf] por quatro operações, duas das quais falham. O [CompletableFuture] de [allOf] falha por sua vez, mas com apenas uma das exceções (linha 9 dos resultados);
  • linhas 43–50: cada operação guardou seu resultado ou sua exceção. Examinamos seu estado usando um [switch]; [exceptionNow()] retorna a exceção original, sem encapsulamento. A falha de [allOf] não impede que as outras operações tenham sucesso (linhas 10 e 12).

Com threads virtuais, a questão não se coloca da mesma forma: o código executado por uma thread virtual é código comum, em que as exceções se propagam normalmente e são interceptadas por [try / catch]. Somente a fronteira entre duas threads exige atenção especial: uma exceção de uma tarefa submetida a um executor é armazenada em seu [Future], e [get()] a relança encapsulada em uma [ExecutionException].

9.5.2. Operações esquecidas

O que acontece com a exceção de uma operação que ninguém aguarda? O programa [Async12.java] demonstra isso:

// uma operação iniciada e depois esquecida: sua exceção se perde
void main() {
    // o tratador das exceções que nenhum código capturou em uma thread
    Thread.setDefaultUncaughtExceptionHandler((thread, e) ->
            IO.println("uncaught exception in [" + thread.getName() + "] : " + e.getMessage()));

    // 1 - um CompletableFuture aguardado: sua exceção é capturada
    try {
        save("a").join();
    } catch (CompletionException e) {
        IO.println("1 - awaited CompletableFuture: exception caught: " + e.getCause().getMessage());
    }

    // 2 - um CompletableFuture esquecido: sua exceção permanece no objeto, ninguém a verá
    save("b");
    IO.println("2 - forgotten CompletableFuture: the call has returned");

    // 3 - uma tarefa submetida a um executor e esquecida: sua exceção permanece no Future
    ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();
    executor.submit(() -> saveBlocking("c"));
    IO.println("3 - forgotten Future: the task is started");

    // 4 - uma thread: a exceção não capturada encerra a thread e chega ao tratador
    Thread.ofVirtual().name("recorder").start(() -> saveBlocking("d"));
    IO.println("4 - virtual thread started");

    // 5 - início sem espera, mas tratando a falha
    save("e").exceptionally(e -> {
        IO.println("5 - failure reported by exceptionally: " + e.getCause().getMessage());
        return null;
    });

    // o programa continua seu trabalho…
    for (int i = 1; i <= 4; i++) {
        sleep(100);
        IO.println("the program is working (" + i + ")");
    }
    executor.close();
    IO.println("normal end of the program");
}

// uma operação assíncrona que falha após 200 ms
CompletableFuture<Void> save(String data) {
    return new CompletableFuture<Void>()
            .completeOnTimeout(null, 200, TimeUnit.MILLISECONDS)
            .thenRun(() -> {
                throw new IllegalStateException("failed to save [" + data + "]");
            });
}

// a mesma operação, escrita de forma bloqueante
void saveBlocking(String data) {
    sleep(200);
    throw new IllegalStateException("failed to save [" + data + "]");
}

// Thread.sleep sem exceção verificada: uma interrupção vira uma CancellationException
void sleep(long ms) {
    try {
        Thread.sleep(ms);
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        throw new CancellationException("wait interrupted");
    }
}

Resultados:

> java Async12.java
1 - awaited CompletableFuture: exception caught: failed to save [a]
2 - forgotten CompletableFuture: the call has returned
3 - forgotten Future: the task is started
4 - virtual thread started
the program is working (1)
5 - failure reported by exceptionally: failed to save [e]
uncaught exception in [recorder] : failed to save [d]
the program is working (2)
the program is working (3)
the program is working (4)
normal end of the program

Comentários:

  • linhas 4–5: [Thread.setDefaultUncaughtExceptionHandler] configura o handler chamado quando uma exceção não é capturada por nenhum código de uma thread, logo antes do fim dessa thread. Sem ele, a JVM exibe o stack trace da exceção na saída de erro;
  • linhas 8–12: a operação é aguardada e sua exceção é interceptada normalmente;
  • linhas 14–16: a operação é lançada e depois esquecida. Sua exceção é armazenada no [CompletableFuture], que ninguém jamais consultará: ela é perdida, sem sequer uma mensagem;
  • linhas 18–21: o mesmo vale para uma tarefa submetida por [submit] a um executor: sua exceção é armazenada no [Future] retornado, que é ignorado;
  • linha 24: uma thread lançada diretamente não tem [Future]: a exceção que ela não trata encerra a thread e chega ao handler de exceções não capturadas (linha 8 dos resultados). O programa, porém, continua;
  • linhas 28–31: a maneira correta de iniciar uma operação sem esperar por ela: anexar a ela uma continuação [exceptionally] (ou [whenComplete]) que trate a falha, neste caso exibindo uma mensagem (linha 7);
  • As linhas 33–39 mostram que, em todos os casos, o programa continua em execução até seu término normal. Isso difere de algumas linguagens, nas quais uma exceção não capturada pode encerrar o programa; em Java, ela passa despercebida, o que não é melhor: um erro de registro que ninguém vê significa dados perdidos.

A regra é, portanto: uma operação iniciada deve ser concluída ([join], [get], [allOf], ou o método [close] de um executor, que espera suas tarefas), ou receber uma continuação que trate sua falha. Ferramentas de análise de código (SpotBugs, inspeções do IntelliJ IDEA) também podem sinalizar o resultado ignorado de um método que retorna um [Future].

9.6. Cancelamento e prazos

9.6.1. Future.cancel e encerramento de threads

Uma operação de longa duração deve poder ser cancelada: o usuário clicou em [Cancel], um cliente do servidor se desconectou, a aplicação foi encerrada ou ocorreu um timeout. Java usa para isso um mecanismo cooperativo: a interrupção de threads:

  • o método [interrupt()] de uma thread ativa seu flag de interrupção; ele não interrompe a thread (o método [Thread.stop], que forçava a parada, está obsoleto desde o Java 20: ele chama [UnsupportedOperationException]);
  • se a thread estiver bloqueada em uma espera interrompível ([Thread.sleep], [Object.wait], [Thread.join], [BlockingQueue.take], [Future.get]…), a espera é imediatamente interrompida e dispara uma [InterruptedException], limpando o flag;
  • uma thread que realiza cálculos verifica regularmente seu próprio indicador usando [Thread.currentThread().isInterrupted()] e termina de forma ordenada se ele estiver ativado;
  • o método [cancel(true)] de um [Future] retornado por um executor leva a tarefa ao estado [CANCELLED] e interrompe a thread que a executa ([cancel(false)] apenas impede que a tarefa comece, caso ainda não tenha começado). Após o cancelamento, [get()] lança uma [CancellationException].

O mecanismo é cooperativo: ninguém interrompe uma operação à força; a operação se interrompe por conta própria em um ponto em que pode fazê-lo de forma limpa. É por isso que um método que intercepta uma [InterruptedException] não deve ignorá-la: deve propagá-la, encerrar-se ou, no mínimo, reativar o flag com [Thread.currentThread().interrupt()] para que o código chamador saiba que uma interrupção foi solicitada (é o que nosso método [sleep] faz).

O programa [Async13.java] cancela um download simulado de várias maneiras:

// cancelamento de uma operação: Future.cancel(true) e interrupção de thread
long start = System.nanoTime();

void main() throws InterruptedException, ExecutionException {
    try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
        // 1 - não esperamos o resultado por mais de 1,2 segundo e depois cancelamos a operação
        Future<?> download1 = executor.submit(() -> download(10));
        try {
            download1.get(1200, TimeUnit.MILLISECONDS);
        } catch (TimeoutException e) {
            // cancel(true) interrompe a thread que executa a tarefa
            download1.cancel(true);
            display("1 - " + e.getClass().getSimpleName() + ", state: " + download1.state());
        }

        // 2 - um cálculo que verifica por conta própria, regularmente, se foi interrompido
        start = System.nanoTime();
        Future<Long> computation = executor.submit(this::compute);
        Thread.sleep(300);
        computation.cancel(true);
        try {
            display("2 - result: " + computation.get());
        } catch (CancellationException e) {
            display("2 - get() throws " + e.getClass().getSimpleName() + ", state: " + computation.state());
        }
        Thread.sleep(100);

        // 3 - o cancelamento é solicitado pelo programa após 700 ms
        start = System.nanoTime();
        Future<?> download3 = executor.submit(() -> download(10));
        Thread.sleep(700);
        display("3 - the program requests the cancellation");
        download3.cancel(true);
        display("3 - isCancelled=" + download3.isCancelled());
        Thread.sleep(100);

        // 4 - cancel() em um CompletableFuture não interrompe a operação que ele representa
        start = System.nanoTime();
        CompletableFuture<Void> download4 = CompletableFuture.runAsync(() -> download(3), executor);
        Thread.sleep(400);
        download4.cancel(true);
        display("4 - CompletableFuture cancelled: isCancelled=" + download4.isCancelled()
                + ", but the operation continues");
    } // close() espera o fim de todas as tarefas
}

// simula o download de [nbBlocks] blocos de dados (um bloco a cada 300 ms)
void download(int nbBlocks) {
    try {
        for (int i = 1; i <= nbBlocks; i++) {
            // uma espera bloqueante é interrompida assim que a thread é interrompida
            Thread.sleep(300);
            display("  block " + i + "/" + nbBlocks + " received");
        }
    } catch (InterruptedException e) {
        display("  download interrupted");
    }
}

// um cálculo longo que verifica o flag de interrupção de sua thread a cada 1.000.000 de iterações
long compute() {
    long sum = 0;
    for (long i = 0; i < 100_000_000_000L; i++) {
        if (i % 1_000_000 == 0 && Thread.currentThread().isInterrupted()) {
            display("  computation interrupted at round " + i);
            return -1;
        }
        sum += i % 7;
    }
    return sum;
}

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

Resultados:

> java Async13.java
  318 ms :   block 1/10 received
  638 ms :   block 2/10 received
  939 ms :   block 3/10 received
 1212 ms :   download interrupted
 1214 ms : 1 - TimeoutException, state: CANCELLED
  301 ms : 2 - get() throws CancellationException, state: CANCELLED
  303 ms :   computation interrupted at round 131000000
  302 ms :   block 1/10 received
  603 ms :   block 2/10 received
  701 ms : 3 - the program requests the cancellation
  702 ms :   download interrupted
  702 ms : 3 - isCancelled=true
  309 ms :   block 1/3 received
  404 ms : 4 - CompletableFuture cancelled: isCancelled=true, but the operation continues
  609 ms :   block 2/3 received
  910 ms :   block 3/3 received

Comentários:

  • Linhas 47–58: o download simulado recebe um bloco a cada 300 ms. Ele é executado por uma thread virtual e usa uma espera bloqueante, [Thread.sleep], que termina assim que a thread é interrompida: [InterruptedException] sai do laço, e o download para sinalizando isso. Ele não exige nenhum parâmetro especial para ser cancelável: as esperas de [java.util.concurrent] reagem da mesma forma à interrupção, assim como, em uma thread virtual, as operações de E/S bloqueantes em sockets (o socket é então fechado e a operação lança uma [SocketException]);
  • Linhas 6–14: [get(1200, TimeUnit.MILLISECONDS)] espera o resultado por no máximo 1,2 segundo e depois lança uma [TimeoutException]. A espera é abandonada, mas não a operação: ela é cancelada explicitamente com [cancel(true)], que interrompe a thread virtual do download. A thread recebeu três blocos e para em 1.200 ms (linhas 2–6 dos resultados);
  • linhas 16–26: um cálculo cancelável (não uma espera). O método [compute] (linhas 60–71) verifica o flag de interrupção de sua thread a cada milhão de ciclos e para se ele estiver ativado. O programa o aborta após 300 ms: [get()] lança imediatamente uma [CancellationException] (linha 7), e o cálculo para por conta própria pouco depois (linha 8);
  • linhas 28–35: o programa solicita o cancelamento após 700 ms. Ele tem efeito imediato: a espera pelo terceiro bloco é interrompida (linhas 11–13);
  • Linhas 37–43: uma armadilha a conhecer. O método *[cancel] de um *[CompletableFuture] o encerra no estado *[CANCELLED], mas não interrompe nada: um [CompletableFuture] não sabe qual thread, se houver, está trabalhando para ele (seu parâmetro [mayInterruptIfRunning] é ignorado). O download continua até o fim (linhas 16–17); apenas seu resultado será ignorado. Para que um [CompletableFuture] possa interromper a operação que representa, essa operação deve monitorar o estado do [CompletableFuture] ([isCancelled()]), ou o [Future]* ou a thread da tarefa deve ser mantido para interrompê-la;
  • Linha 44: o método [close()] do executor espera a conclusão de todas as tarefas, inclusive a da etapa 4.

9.6.2. Vários processos, vários desfechos

O programa [Async14.java] lança cinco processos com duração de 1 a 5 segundos: o processo nº 3 lança uma exceção e o processo nº 4 é cancelado. Ele trata cada tarefa assim que ela termina, independentemente de como terminou, e sempre sabe de qual tarefa se trata:

// cinco processamentos de 1 a 5 segundos executados por threads virtuais:
// o nº 3 lança uma exceção, o nº 4 é cancelado
long start;

void main() throws InterruptedException {
    start = System.nanoTime();
    try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();
         ScheduledExecutorService scheduler = Executors.newSingleThreadScheduledExecutor()) {
        // o CompletionService entregará cada tarefa assim que ela terminar
        CompletionService<ProcessingResult> service = new ExecutorCompletionService<>(executor);
        List<Future<ProcessingResult>> tasks = new ArrayList<>();
        for (int i = 0; i < 5; i++) {
            int number = i;
            tasks.add(service.submit(() -> sleep(number, number + 1)));
        }
        // cancelamos o processamento nº 4 após 2,5 segundos
        scheduler.schedule(() -> tasks.get(4).cancel(true), 2500, TimeUnit.MILLISECONDS);
        display("the " + tasks.size() + " processings are started");

        // usamos cada processamento assim que ele termina, seja qual for a forma como terminou
        for (int i = 0; i < tasks.size(); i++) {
            Future<ProcessingResult> task = service.take();
            int number = tasks.indexOf(task);
            String outcome = switch (task.state()) {
                case SUCCESS -> String.format("finished: scheduled duration %d s, actual duration %.1f s",
                        task.resultNow().duration(), task.resultNow().actualDuration());
                case FAILED -> "encountered the following error: " + task.exceptionNow().getMessage();
                case CANCELLED -> "cancelled";
                case RUNNING -> "still running?";
            };
            display("processing " + number + " " + outcome);
        }
    }
}

// o processamento: dormir [duration] segundos, em fatias de um segundo
ProcessingResult sleep(int number, int duration) throws InterruptedException {
    long processingStart = System.nanoTime();
    // exceção para o processamento nº 3
    if (number == 3) {
        throw new IllegalStateException("test....");
    }
    for (int i = 1; i <= duration; i++) {
        Thread.sleep(1000);
    }
    // o resultado retornado ao chamador
    return new ProcessingResult(duration, (System.nanoTime() - processingStart) / 1e9);
}

// o resultado de um processamento
record ProcessingResult(int duration, double actualDuration) {
}

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

Resultados:

1
2
3
4
5
6
7
> java Async14.java
 0.0 s : the 5 processings are started
 0.0 s : processing 3 encountered the following error: test....
 1.0 s : processing 0 finished: scheduled duration 1 s, actual duration 1.0 s
 2.0 s : processing 1 finished: scheduled duration 2 s, actual duration 2.0 s
 2.5 s : processing 4 cancelled
 3.0 s : processing 2 finished: scheduled duration 3 s, actual duration 3.0 s

Comentários:

  • Linhas 36–48: o processo. O nº 3 lança uma exceção; os outros "dormem" por [duration] segundos em incrementos de um segundo, com um [Thread.sleep] interrompível, e retornam um resultado — um [record] — que contém a duração programada e a duração real. O método declara [InterruptedException]: ele é chamado por um [Callable], cujo método [call] pode lançar exceções verificadas;
  • linhas 7–8: dois executors declarados no mesmo [try]: o executor de threads virtuais e um [ScheduledExecutorService], um executor capaz de executar uma tarefa após um atraso (voltaremos a isso na seção sobre tempo);
  • linhas 10–15: os cinco processos são submetidos ao [CompletionService] já encontrado em [Async10.java], e suas [Future] instâncias são armazenadas em uma lista;
  • linha 17: o [ScheduledExecutorService] cancelará o processo nº 4 após 2,5 segundos, embora ainda lhe restem 2,5 segundos de execução;
  • linhas 21–32: [take()] entrega cada processo assim que ele é concluído, independentemente de como terminou: um [Future] cancelado também é entregue. Não chamamos [get()], que lançaria uma exceção, mas examinamos o estado do [Future] usando uma expressão [switch] que cobre as quatro constantes de [Future.State] (o compilador verifica que nenhuma está faltando). O número do processamento é determinado pela posição de seu [Future] na lista ([indexOf]);
  • 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 em 2,5 segundos.

9.6.3. Limitando a duração de uma espera

O programa [Async15.java] oferece ferramentas para limitar a duração de uma espera: os métodos [orTimeout] e [completeOnTimeout] de [CompletableFuture] (Java 9) e o método [get] com um prazo, de [Future]. Ele também mostra como combinar duas causas de parada.

// limitação da duração de uma espera: orTimeout, completeOnTimeout, get(timeout)
long start = System.nanoTime();

void main() throws InterruptedException, ExecutionException {
    try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
        // 1 - orTimeout: não esperamos mais de um segundo
        CompletableFuture<String> slow = CompletableFuture.supplyAsync(
                () -> queryBlocking("slow-server", 3000), executor);
        try {
            display("1 - answer: " + slow.orTimeout(1, TimeUnit.SECONDS).join());
        } catch (CompletionException e) {
            display("1 - " + e.getCause().getClass().getSimpleName() + ", state: " + slow.state());
        }
        // a própria operação continua: deixamos que ela termine
        Thread.sleep(2200);

        // 2 - completeOnTimeout: passado um segundo, nos contentamos com uma resposta padrão
        start = System.nanoTime();
        String answer = query("slow-server", 3000)
                .completeOnTimeout("default answer", 1, TimeUnit.SECONDS)
                .join();
        display("2 - " + answer);

        // 3 - para realmente parar a operação, interrompemos a thread que a executa
        start = System.nanoTime();
        Future<String> slow3 = executor.submit(() -> queryBlocking("slow-server", 3000));
        try {
            display("3 - answer: " + slow3.get(1, TimeUnit.SECONDS));
        } catch (TimeoutException e) {
            slow3.cancel(true);
            display("3 - one-second timeout exceeded, operation cancelled, state: " + slow3.state());
        }
    }

    // 4 - duas causas de parada: o timeout específico de cada processamento e uma parada geral
    start = System.nanoTime();
    CompletableFuture<Void> generalStop = new CompletableFuture<>();
    CompletableFuture<Void> all = CompletableFuture.allOf(
            processWithTimeout("fast", 500, 1000, generalStop),
            processWithTimeout("slow", 3000, 1000, generalStop),
            processWithTimeout("medium", 1500, 2000, generalStop));
    // o chamador solicita a parada geral após 1.200 ms
    Thread.sleep(1200);
    display("4 - general stop requested");
    generalStop.complete(null);
    all.join();
}

// um processamento limitado a [timeout] milissegundos, que também pode ser interrompido pelo chamador
CompletableFuture<Void> processWithTimeout(String name, int duration, int timeout, CompletableFuture<Void> stop) {
    CompletableFuture<String> answer = query(name, duration).orTimeout(timeout, TimeUnit.MILLISECONDS);
    // a parada geral cancela a espera pela resposta
    stop.thenRun(() -> answer.cancel(false));
    // examinamos a forma como a espera terminou
    return answer.handle((text, e) -> switch (e) {
        case null -> text;
        case TimeoutException _ -> name + " : timeout of " + timeout + " ms exceeded";
        case CancellationException _ -> name + " : stopped at the caller's request";
        default -> name + " : " + e;
    }).thenAccept(message -> display("4 - " + message));
}

// simula um servidor que responde após [duration] milissegundos
CompletableFuture<String> query(String server, int duration) {
    return new CompletableFuture<String>()
            .completeOnTimeout(server + " answered in " + duration + " ms", duration, TimeUnit.MILLISECONDS);
}

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

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

Resultados:

> java Async15.java
 1028 ms : 1 - TimeoutException, state: FAILED
 3025 ms :   slow-server has finished its work
 1001 ms : 2 - default answer
 1003 ms :   slow-server was interrupted
 1004 ms : 3 - one-second timeout exceeded, operation cancelled, state: CANCELLED
  501 ms : 4 - fast answered in 500 ms
 1005 ms : 4 - slow : timeout of 1000 ms exceeded
 1206 ms : 4 - general stop requested
 1207 ms : 4 - medium : stopped at the caller's request

Comentários:

  • linhas 7–8: a operação lenta é um método bloqueante (linhas 69–79), executado por uma thread virtual usando [supplyAsync] com um executor;
  • Linha 10: [orTimeout(timeout, unit)] encerra o [CompletableFuture] com uma [TimeoutException] se ele não for concluído dentro do prazo. Esta é a escrita direta da "corrida" com [anyOf] do programa [Async09.java]. [orTimeout] não cria um novo [CompletableFuture]: ele modifica aquele ao qual se aplica (e o retorna); por isso o estado de [slow] é [FAILED] (linha 2 dos resultados);
  • Linhas 14–15: [orTimeout] aborta a espera, não a operação: a thread virtual continua a executar e conclui seu trabalho aos 3 segundos (linha 3), sem utilidade. É o mesmo problema visto antes com [cancel]: um [CompletableFuture] não pode interromper a operação que representa;
  • linhas 17–22: [completeOnTimeout(value, timeout, unit)] encerra o [CompletableFuture] com um valor padrão se ele não for concluído dentro do prazo: após um segundo, uma "resposta padrão" é retornada (linha 4);
  • linhas 24–32: para realmente interromper a operação, ela é submetida ao executor; esperamos seu [Future] por no máximo um segundo e depois a cancelamos com [cancel(true)], que interrompe sua thread: a operação para após 1 segundo (linhas 5–6). Esta é a solução preferida quando a operação é bloqueante e interrompível;
  • linhas 49–61: um processo pode ser interrompido por vários motivos; aqui, seu próprio timeout e uma solicitação geral de parada do chamador:
    • linha 51: o timeout próprio do processo é definido com [orTimeout];
    • linha 53: o encerramento geral é ele próprio um [CompletableFuture<Void>], que o chamador concluirá; anexa-se a ele uma continuação que cancela a espera pela resposta;
    • linhas 55–60: seja qual for a causa, a espera termina em falha; [handle] verifica a exceção usando um [switch] sobre os tipos (Java 21): [case null] para sucesso, [case TimeoutException _] para timeout, [case CancellationException _] para encerramento geral. O caractere [_] (Java 22) é uma variável anônima: o tipo é testado sem a necessidade de nomear o objeto;
  • linhas 36–46: três processos e um encerramento geral solicitado em 1.200 ms ao concluir o [CompletableFuture] e [generalStop]. O processo [fast] termina normalmente; o processo [slow] excede seu limite de um segundo; o processo [medium], que dispunha de dois segundos, é encerrado pelo encerramento geral (linhas 7–10).

9.7. Informando o progresso

Uma operação de longa duração costuma precisar informar seu progresso (uma barra de progresso, uma porcentagem). A abordagem mais simples é passar a ela uma função de callback que receba os relatórios de progresso: um [Consumer<T>], a interface funcional do Capítulo 7 cujo único método, [accept(T)], recebe um valor. A operação chama [accept] a cada etapa; ela desconhece como os relatórios de progresso serão exibidos.

Em uma interface gráfica, os relatórios — gerados pela thread que executa a operação — não podem atualizar diretamente os componentes gráficos: o [Consumer] deve delegar a atualização à thread da interface ([SwingUtilities.invokeLater(() -> bar.setValue(percentage))] com Swing, [Platform.runLater] com JavaFX). Em um programa de console, ele pode exibir a saída diretamente. O programa [Async16.java] simula uma cópia de arquivos que o usuário pode cancelar digitando [Enter]:

// informação do progresso de uma operação com um Consumer; o usuário pode cancelá-la
void main() throws InterruptedException {
    try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
        IO.println("Copy in progress, press [Enter] to cancel it");
        // a cópia é executada por uma thread virtual; o método display exibe seus relatórios
        Future<Integer> copy = executor.submit(() -> copy(8, this::display));
        // outra thread virtual espera o usuário pressionar [Enter] para cancelar a cópia
        Thread.ofVirtual().start(() -> {
            // readln retorna null se a entrada padrão estiver fechada: não cancelamos nada
            if (IO.readln() != null) {
                copy.cancel(true);
            }
        });
        try {
            IO.println("Copy finished: " + copy.get() + " files copied");
        } catch (CancellationException e) {
            IO.println("Copy cancelled by the user");
        } catch (ExecutionException e) {
            IO.println("Copy failed: " + e.getCause());
        }
    }
}

// a operação não sabe como seu progresso é exibido: ela apenas o informa
int copy(int nbFiles, Consumer<Progress> progress) throws InterruptedException {
    for (int i = 1; i <= nbFiles; i++) {
        // a cópia de um arquivo
        Thread.sleep(300);
        // o relatório de progresso (o chamador pode não querê-lo: progress é então null)
        if (progress != null) {
            progress.accept(new Progress(100 * i / nbFiles, "file" + i + ".dat"));
        }
    }
    return nbFiles;
}

// um relatório de progresso
record Progress(int percentage, String file) {
}

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

Resultados sem cancelamento:

> java Async16.java
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:

1
2
3
4
5
6
7
8
> java Async16.java
Copy in progress, press [Enter] to cancel it
[##..................]  12 % file1.dat
[#####...............]  25 % file2.dat
[#######.............]  37 % file3.dat
[##########..........]  50 % file4.dat
[############........]  62 % file5.dat
Copy cancelled by the user

Comentários:

  • Linhas 24–35: a operação recebe um [Consumer<Progress>]. Após cada arquivo, ela informa seu progresso por meio de um objeto [Progress] (um [record] que inclui a porcentagem e o nome do arquivo). Um chamador que não deseja relatórios passa [null], daí a verificação na linha 30;
  • linhas 41–46: exibição de um relatório: uma barra de 20 caracteres construída com [String.repeat] (Java 11). A referência de método [this::display] (linha 6) é o [Consumer<Progress>] passado à operação;
  • linha 6: a cópia é realizada por uma thread virtual;
  • linhas 8–13: outra thread virtual espera o usuário digitar [Enter] ([IO.readln()] é uma leitura bloqueante, e é por isso que se usa essa thread: é ela que fica bloqueada, não o programa), e então cancela a cópia com [cancel(true)], o que interrompe o [Thread.sleep] da linha 28. O programa não a espera: ela é uma thread daemon, abandonada no fim do programa se o usuário não tiver digitado nada;
  • linhas 14–20: o programa espera o fim da cópia. Um cancelamento resulta em uma [CancellationException], enquanto uma falha de cópia resulta em uma [ExecutionException].

9.8. Entrada/saída assíncrona

9.8.1. Arquivos

A E/S é a própria razão de ser do processamento assíncrono. Java oferece duas famílias de classes para arquivos:

  • as classes "clássicas", bloqueantes: [Files] ([readAllLines], [readString], [lines], [writeString], [newBufferedReader], [newBufferedWriter]…), [BufferedReader], [BufferedWriter]. Elas agora são executadas em uma thread virtual quando não se quer bloquear uma thread importante;
  • a classe [AsynchronousFileChannel] (Java 7), cujas operações retornam um [Future] ou chamam um [CompletionHandler]. Ela raramente é usada: no Linux, ela na verdade realiza leituras bloqueantes em um pool de threads interno da JVM, e sua interface é incômoda.

O programa [Async17.java] exibe as duas famílias lendo o arquivo das faixas do imposto a partir do programa principal, [TaxData.txt], localizado no diretório do programa:

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á neste exercício). O programa é executado na pasta [09-async] e procura seus arquivos na pasta atual.

// E/S de arquivos: AsynchronousFileChannel e depois E/S bloqueante em uma thread virtual
final Path data = Path.of("TaxData.txt");
final Path report = Path.of("report-17.txt");

void main() throws InterruptedException {
    // 1 - AsynchronousFileChannel (Java 7): uma leitura assíncrona, retornada como um CompletableFuture
    String content = readAsynchronously(data).join();
    IO.println("1 - AsynchronousFileChannel: " + content.lines().count() + " lines");

    // 2 a 7 - E/S bloqueante comum, executada por uma thread virtual
    Thread.ofVirtual().start(() -> {
        try {
            processFiles();
        } catch (IOException e) {
            IO.println("error: " + e);
        }
    }).join();
}

// lê um arquivo inteiro (pequeno) com um AsynchronousFileChannel
CompletableFuture<String> readAsynchronously(Path file) {
    CompletableFuture<String> result = new CompletableFuture<>();
    try {
        AsynchronousFileChannel channel = AsynchronousFileChannel.open(file, StandardOpenOption.READ);
        ByteBuffer buffer = ByteBuffer.allocate((int) channel.size());
        // a leitura é iniciada; o objeto de callback concluirá o CompletableFuture
        channel.read(buffer, 0, buffer, new CompletionHandler<Integer, ByteBuffer>() {
            @Override
            public void completed(Integer nbBytes, ByteBuffer read) {
                result.complete(new String(read.array(), 0, nbBytes, StandardCharsets.UTF_8));
            }

            @Override
            public void failed(Throwable e, ByteBuffer read) {
                result.completeExceptionally(e);
            }
        });
        // o canal será fechado quando a leitura terminar, seja qual for seu resultado
        result.whenComplete((text, e) -> close(channel));
    } catch (IOException e) {
        result.completeExceptionally(e);
    }
    return result;
}

void processFiles() throws IOException {
    // 2 - leitura do arquivo inteiro em uma única operação
    List<String> lines = Files.readAllLines(data);
    IO.println("2 - Files.readAllLines: " + lines.size() + " lines");

    // 3 - leitura linha a linha com um BufferedReader
    List<TaxBracket> brackets = new ArrayList<>();
    try (BufferedReader reader = Files.newBufferedReader(data)) {
        String line;
        // readLine retorna null no fim do arquivo
        while ((line = reader.readLine()) != null) {
            brackets.add(TaxBracket.parse(line));
        }
    }
    IO.println("3 - BufferedReader.readLine: " + brackets.size() + " brackets, 2nd: " + brackets.get(1));

    // 4 - Files.lines retorna um Stream de linhas, lidas sob demanda
    try (Stream<String> stream = Files.lines(data)) {
        IO.println("4 - Files.lines: " + stream.count() + " lines");
    }

    // 5 - escrita com um BufferedWriter
    try (BufferedWriter writer = Files.newBufferedWriter(report)) {
        writer.write("Brackets of the tax scale (exercise: 2004 tax scale on 2003 income)");
        writer.newLine();
        for (int i = 0; i < brackets.size(); i++) {
            TaxBracket bracket = brackets.get(i);
            String limit = bracket.limit().signum() == 0 ? "beyond"
                    : String.format("up to %,d €", bracket.limit().intValue());
            writer.write(String.format("bracket %d : %-18s rate %.1f %%",
                    i + 1, limit, bracket.coeffR().multiply(BigDecimal.valueOf(100))));
            writer.newLine();
        }
    }

    // 6 - leitura do arquivo inteiro como uma string
    String text = Files.readString(report);
    IO.print("5 and 6 - content of [" + report + "] :\n" + text);

    // 7 - acréscimo ao fim do arquivo e depois sua exclusão
    Files.writeString(report, "end of the report\n", StandardOpenOption.APPEND);
    IO.println("7 - last line: " + Files.readAllLines(report).getLast());
    Files.delete(report);
}

// fecha um canal sem exceção verificada
void close(Channel channel) {
    try {
        channel.close();
    } catch (IOException e) {
        IO.println("error while closing: " + e);
    }
}

// uma faixa do imposto; o arquivo usa o ponto decimal, que o BigDecimal entende
record TaxBracket(BigDecimal limit, BigDecimal coeffR, BigDecimal coeffN) {
    static TaxBracket parse(String line) {
        String[] fields = line.split(":");
        return new TaxBracket(new BigDecimal(fields[0]), new BigDecimal(fields[1]),
                new BigDecimal(fields[2]));
    }
}

Resultados:

> java Async17.java
1 - AsynchronousFileChannel: 7 lines
2 - Files.readAllLines: 7 lines
3 - BufferedReader.readLine: 7 brackets, 2nd: TaxBracket[limit=8382, coeffR=0.068, coeffN=291.09]
4 - Files.lines: 7 lines
5 and 6 - content of [report-17.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 : beyond             rate 48.1 %
7 - last line: end of the report

Comentários:

  • Linhas 20–44: leitura com um [AsynchronousFileChannel], apresentada na forma de um [CompletableFuture<String>]. Esta é a técnica geral para converter uma API com métodos de callback em um [CompletableFuture]: criamos um [CompletableFuture] "em andamento" (linha 22), o retornamos imediatamente (linha 43), e os métodos de callback o concluem, fornecendo o resultado ([complete], linha 30) ou a exceção ([completeExceptionally], linha 35). O objeto de callback é uma classe anônima que implementa [CompletionHandler<Integer, ByteBuffer>]: o resultado de uma operação de leitura é o número de bytes lidos, e o objeto passado aqui é o próprio buffer. Uma única operação de leitura basta para um arquivo pequeno; um arquivo grande exigiria operações de leitura sucessivas, que os métodos de callback precisariam encadear;
  • linha 39: [whenComplete] fecha o canal quando a operação de leitura termina, com ou sem sucesso;
  • Linhas 11–17: as outras operações são operações de E/S bloqueantes comuns, agrupadas no método [processFiles] e executadas por uma thread virtual. A lambda de um [Runnable] não pode lançar uma exceção verificada: a [IOException] é interceptada dentro da lambda;
  • linha 48: [Files.readAllLines] lê o arquivo inteiro e retorna uma lista de suas linhas (usando UTF-8 por padrão, como todos os métodos de [Files]);
  • linhas 52–59: leitura linha a linha usando um [BufferedReader]; [readLine()] retorna [null] no fim do arquivo. Cada linha é convertida em [TaxBracket] pelo método [parse] do record (linhas 100–107); os números são [BigDecimal], cujo construtor espera um ponto decimal, independentemente do idioma da máquina. A representação de um record produzida por seu método [toString] aparece na linha 4 dos resultados;
  • linhas 63–65: [Files.lines] retorna um [Stream<String>] formado por linhas lidas sob demanda: ao contrário de [readAllLines], ele não carrega o arquivo inteiro na memória. Este é o método preferido para arquivos grandes. O stream mantém o arquivo aberto: ele deve ser fechado, daí o [try] com recurso;
  • Linhas 68–79: escrita com um [BufferedWriter], que é fechado (e, assim, descarregado em disco) ao sair do [try]. O formato [%,d] insere o separador de milhares do idioma da máquina (um espaço fino sem quebra em francês);
  • Linhas 82–88: [Files.readString] (Java 11) relê o arquivo escrito; [Files.writeString], usando a opção [StandardOpenOption.APPEND], acrescenta uma linha a ele; [getLast()] (Java 21) retorna o último elemento da lista, e depois o arquivo é excluído.

Lembre-se da limitação mencionada acima: as leituras e escritas de arquivos fixam a thread virtual à sua thread portadora durante a operação, e a JVM compensa adicionando uma thread portadora. Para arquivos locais, isso raramente é perceptível; para operações de rede, as threads virtuais de fato liberam suas portadoras durante as esperas.

9.8.2. Rede: HttpClient

O cliente HTTP de Java, [java.net.http.HttpClient] (Java 11), oferece as duas abordagens: [send], que é bloqueante e retorna a resposta, e [sendAsync], que retorna imediatamente um [CompletableFuture] contendo a resposta. O Capítulo 12 examinará isso em detalhes; o programa [Async18.java] simplesmente 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) ou bloqueantes (send) a um pequeno servidor local
import com.sun.net.httpserver.HttpServer;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

final int port = 27510;
final List<String> cities = List.of("Angers", "Brest", "Colmar", "Dijon", "Évry", "Foix");
long start;

void main() throws IOException, InterruptedException, ExecutionException {
    // um servidor HTTP que leva um segundo para dar a "temperature" de uma cidade
    HttpServer server = HttpServer.create(new InetSocketAddress(InetAddress.getLoopbackAddress(), port), 0);
    server.createContext("/temperature", exchange -> {
        // a requisição tem a forma /temperature?city=xxx
        String parameter = exchange.getRequestURI().getRawQuery().substring("city=".length());
        String city = URLDecoder.decode(parameter, StandardCharsets.UTF_8);
        sleep(1000);
        byte[] response = (city + " : " + (10 + city.length()) + " °C").getBytes(StandardCharsets.UTF_8);
        exchange.sendResponseHeaders(200, response.length);
        try (OutputStream stream = exchange.getResponseBody()) {
            stream.write(response);
        }
    });
    // cada requisição recebida é tratada por uma thread virtual
    server.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
    server.start();

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

        // 1 - sendAsync retorna imediatamente um CompletableFuture<HttpResponse<String>>
        start = System.nanoTime();
        List<CompletableFuture<String>> responses = cities.stream()
                .map(city -> client.sendAsync(request(city), HttpResponse.BodyHandlers.ofString())
                        .thenApply(HttpResponse::body))
                .toList();
        CompletableFuture.allOf(responses.toArray(CompletableFuture[]::new)).join();
        display("1 - sendAsync: " + responses.stream().map(CompletableFuture::resultNow).toList());

        // 2 - send é bloqueante: nós o chamamos a partir de threads virtuais
        start = System.nanoTime();
        try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
            List<Future<String>> responses2 = new ArrayList<>();
            for (String city : cities) {
                responses2.add(executor.submit(
                        () -> client.send(request(city), HttpResponse.BodyHandlers.ofString()).body()));
            }
            List<String> texts = new ArrayList<>();
            for (Future<String> response : responses2) {
                texts.add(response.get());
            }
            display("2 - send on virtual threads: " + texts);
        }
    } finally {
        server.stop(0);
    }
}

// a requisição GET que pede a temperatura de uma cidade
HttpRequest request(String city) {
    String parameter = URLEncoder.encode(city, StandardCharsets.UTF_8);
    URI address = URI.create("http://localhost:" + port + "/temperature?city=" + parameter);
    return HttpRequest.newBuilder(address).build();
}

// Thread.sleep sem exceção verificada: uma interrupção vira uma CancellationException
void sleep(long ms) {
    try {
        Thread.sleep(ms);
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        throw new CancellationException("wait interrupted");
    }
}

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

Resultados:

1
2
3
> java Async18.java
 1033 ms : 1 - sendAsync: [Angers : 16 °C, Brest : 15 °C, Colmar : 16 °C, Dijon : 15 °C, Évry : 14 °C, Foix : 14 °C]
 1023 ms : 2 - send on virtual threads: [Angers : 16 °C, Brest : 15 °C, Colmar : 16 °C, Dijon : 15 °C, Évry : 14 °C, Foix : 14 °C]

Comentários:

  • linhas 12–27: o servidor. O arquivo da JVM contém um pequeno servidor HTTP, a classe [HttpServer] do módulo [jdk.httpserver], importada na linha 2 (um arquivo compacto importa automaticamente apenas o módulo [java.base]; as classes do cliente, do módulo [java.net.http], são importadas nas linhas 3–5). [createContext] associa um handler ao caminho [/temperature] — uma lambda que recebe a troca HTTP: ela decodifica o parâmetro [city] do endereço solicitado, espera um segundo e depois envia a resposta. A linha 26 faz cada requisição ser processada por uma thread virtual: um servidor configurado dessa forma pode atender milhares de clientes em espera;
  • Linhas 29–31: o cliente é criado por um construtor ([newBuilder]) que define aqui a versão do protocolo. Desde o Java 21, ele implementa [AutoCloseable] e é declarado em um [try] com recurso. Uma requisição inicial serve para "aquecer" a JVM: na primeira vez que um cliente é usado, ele carrega numerosas classes, o que distorceria a medição seguinte em algumas centenas de milissegundos;
  • linhas 33–40: [sendAsync(request, handler)] envia a requisição e retorna imediatamente um [CompletableFuture<HttpResponse<String>>]; o handler de corpo [BodyHandlers.ofString()] indica que o corpo da resposta deve ser lido como uma string. [thenApply(HttpResponse::body)] retém apenas o corpo. As seis requisições são enviadas simultaneamente, e suas 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";
  • linhas 42–55: [send] é bloqueante; ele é chamado a partir de seis threads virtuais. O resultado é o mesmo: um segundo para as seis requisições (linha 3), e nenhuma thread do sistema fica bloqueada;
  • linhas 61–66: 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 usando [URLDecoder.decode] (linha 17).

9.9. Streams assíncronos de valores

Uma operação assíncrona retorna um resultado depois de certo tempo. Um stream ([Stream]) ou um iterador retorna uma sequência de valores, produzidos sob demanda. Às vezes é necessário combinar os dois: 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… Outras linguagens têm um tipo dedicado para isso; Java oferece dois modelos:

  • o modelo "pull": o consumidor solicita o próximo valor e espera até que ele esteja disponível. Com threads virtuais, isso é simplesmente um [Iterator] ou um [Stream] em que a produção de cada valor é bloqueante, lido por uma thread virtual;
  • o modelo "push": o produtor envia valores aos seus assinantes à medida que são produzidos, e os assinantes controlam a vazão. Este é o modelo de streams reativos, padronizado pelas interfaces [java.util.concurrent.Flow] (Java 9).

9.9.1. O modelo pull: um Stream lido por uma thread virtual

O programa [Async19.java] produz medições — uma a cada 200 ms — na forma de um [Stream<Measurement>]:

// uma sequência de valores produzidos com esperas: um Stream "bloqueante" lido por uma thread virtual
long start;

void main() throws InterruptedException {
    // todo o trabalho é feito por uma thread virtual: suas esperas não bloqueiam nenhuma thread carrier
    Thread.ofVirtual().start(this::consume).join();
}

void consume() {
    start = System.nanoTime();
    // 1 - cada valor é processado assim que é produzido
    try (Stream<Measurement> measurements = readMeasurements("sensor-1", 4)) {
        measurements.forEach(measurement -> display("1 - received " + measurement));
    }

    // 2 - podemos sair do laço antes do fim: o produtor não produz os valores seguintes
    start = System.nanoTime();
    try (Stream<Measurement> measurements = readMeasurements("sensor-2", 100)) {
        Iterator<Measurement> iterator = measurements.iterator();
        while (iterator.hasNext()) {
            Measurement measurement = iterator.next();
            display("2 - received " + measurement);
            if (measurement.value() >= 22) {
                break;
            }
        }
    }

    // 3 - cancelamento: outra thread interrompe a thread que lê o stream
    start = System.nanoTime();
    Thread reader = Thread.ofVirtual().start(() -> {
        try (Stream<Measurement> measurements = readMeasurements("sensor-3", 100)) {
            measurements.forEach(measurement -> display("3 - received " + measurement));
        } catch (CancellationException e) {
            display("3 - reading cancelled");
        }
    });
    waitForEnd(reader, 700);

    // 4 - todas as operações da Stream API se aplicam ao stream
    start = System.nanoTime();
    String high;
    try (Stream<Measurement> measurements = readMeasurements("sensor-4", 6)) {
        high = measurements
                .filter(measurement -> measurement.value() > 21)
                .map(measurement -> NumberFormat.getInstance().format(measurement.value()))
                .collect(Collectors.joining(" ; ", "[", "]"));
    }
    display("4 - measurements above 21: " + high);
}

// um produtor: uma medição a cada 200 ms, produzida somente quando o consumidor a pede
Stream<Measurement> readMeasurements(String sensor, int count) {
    return IntStream.rangeClosed(1, count)
            .mapToObj(i -> {
                // esperando a próxima medição
                sleep(200);
                return new Measurement(sensor, i, 19.5 + i * 0.75);
            })
            // executado por close(): no fim normal, após um break ou no cancelamento
            .onClose(() -> IO.println("          " + sensor + " : end of production"));
}

// espera [timeout] ms pelo fim de uma thread, depois a interrompe e espera seu fim
void waitForEnd(Thread thread, long timeout) {
    try {
        thread.join(timeout);
        thread.interrupt();
        thread.join();
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
    }
}

// Thread.sleep sem exceção verificada: uma interrupção vira uma CancellationException
void sleep(long ms) {
    try {
        Thread.sleep(ms);
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        throw new CancellationException("wait interrupted");
    }
}

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

// uma medição
record Measurement(String sensor, int number, double value) {
    @Override
    public String toString() {
        return sensor + " no. " + number + " : " + NumberFormat.getInstance().format(value) + " °C";
    }
}

Resultados:

> java Async19.java
  249 ms : 1 - received sensor-1 no. 1 : 20.25 °C
  455 ms : 1 - received sensor-1 no. 2 : 21 °C
  656 ms : 1 - received sensor-1 no. 3 : 21.75 °C
  857 ms : 1 - received sensor-1 no. 4 : 22.5 °C
          sensor-1 : end of production
  200 ms : 2 - received sensor-2 no. 1 : 20.25 °C
  401 ms : 2 - received sensor-2 no. 2 : 21 °C
  603 ms : 2 - received sensor-2 no. 3 : 21.75 °C
  804 ms : 2 - received sensor-2 no. 4 : 22.5 °C
          sensor-2 : end of production
  201 ms : 3 - received sensor-3 no. 1 : 20.25 °C
  402 ms : 3 - received sensor-3 no. 2 : 21 °C
  602 ms : 3 - received sensor-3 no. 3 : 21.75 °C
          sensor-3 : end of production
  702 ms : 3 - reading cancelled
          sensor-4 : end of production
 1206 ms : 4 - measurements above 21: [21.75 ; 22.5 ; 23.25 ; 24]

Comentários:

  • Linhas 52–62: o produtor. Ele retorna um [Stream<Measurement>] construído a partir dos inteiros de 1 a [count]; a função [mapToObj] espera 200 ms e depois retorna uma medição. Como um stream é preguiçoso (lazy), essa função só é chamada quando o consumidor solicita o próximo valor, e cada medição é processada antes que a seguinte seja produzida. [onClose] registra uma ação executada quando o stream é fechado, qualquer que seja o motivo: este é o [finally] do produtor;
  • linha 6: todo o trabalho é feito por uma thread virtual: a espera de 200 ms por cada medição não bloqueia nenhuma thread do sistema;
  • Linhas 11–14: cada medição é processada assim que é produzida: uma a cada 200 ms (linhas 2–5 dos resultados). O stream é declarado em um [try] com recurso: fechá-lo dispara a ação [onClose] (linha 6);
  • linhas 16–27: para sair do laço antes do fim, o stream é percorrido por meio de seu iterador. Após o [break], o produtor não produz as 96 medições restantes, e o stream é fechado ao sair do [try] (linha 11). Os métodos [takeWhile] (Java 9) ou [limit] também permitem interromper um stream;
  • linhas 29–38: cancelamento. O stream é lido por outra thread virtual, que o método [waitForEnd] (linhas 64–73) interrompe após 700 ms. A espera pela quarta medição é interrompida: o método [sleep] lança uma [CancellationException], que atravessa o stream; o [try] com recurso fecha o stream (linha 15 dos resultados), e depois o [catch] informa o cancelamento (linha 16);
  • linhas 40–49: tudo o que a API Stream sabe fazer é aplicado ao stream: filtragem, transformação, coleta. O resultado só está disponível no fim do stream, após 6 × 200 ms;
  • linhas 90–96: o método [toString] do record [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]).

O mesmo padrão se aplica a um [BufferedReader] (suas linhas são lidas sob demanda, e seu método [lines()] retorna um [Stream<String>]), a um [ResultSet], JDBC, ou ao stream de entrada de um socket: em uma thread virtual, um stream bloqueante é um stream assíncrono.

9.9.2. O modelo push: Flow e SubmissionPublisher

A interface [java.util.concurrent.Flow] (Java 9) reúne quatro interfaces internas que padronizam os streams reativos:

  • [Flow.Publisher<T>], o publicador, produz valores; seu método [subscribe] adiciona um assinante a ele;
  • [Flow.Subscriber<T>], o assinante, recebe valores por meio de seu método [onNext], o fim do stream por [onComplete], um erro por [onError]e, no início, o objeto [Flow.Subscription], que o liga ao publicador por meio de [onSubscribe];
  • [Flow.Subscription], a assinatura: [request(n)] solicita [n] valores adicionais, e [cancel()] encerra a assinatura. O publicador nunca envia mais valores do que o assinante solicitou: é a "contrapressão" (backpressure), que impede que um publicador rápido sobrecarregue um assinante lento;
  • [Flow.Processor<T, R>] é ao mesmo tempo assinante e publicador (um nó de transformação).

Java fornece uma implementação do publicador, [SubmissionPublisher<T>], que entrega os valores a cada assinante por meio de um executor e de um buffer específico desse assinante. Bibliotecas reativas (Project Reactor, RxJava) implementam essas mesmas interfaces e acrescentam dezenas de operadores a elas. O programa [Async20.java] publica seis medições para dois assinantes: um monitor rápido que cancela a assinatura quando a temperatura ultrapassa 22 °C e um arquivo lento:

// o modelo "push": java.util.concurrent.Flow e SubmissionPublisher (Java 9)
final long start = System.nanoTime();

void main() throws InterruptedException {
    Subscriber screen = new Subscriber("screen", 0, 22);
    Subscriber archive = new Subscriber("archive", 500, Double.MAX_VALUE);
    // o publisher entrega a distribuição dos valores a um executor e mantém um buffer de 2 valores por assinante
    try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
        var publisher = new SubmissionPublisher<Measurement>(executor, 2);
        publisher.subscribe(screen);
        publisher.subscribe(archive);
        for (int i = 1; i <= 6; i++) {
            sleep(200);
            // submit espera se não houver mais espaço no buffer de um assinante; retorna o atraso estimado
            int lag = publisher.submit(new Measurement("sensor-1", i, 19.5 + i * 0.75));
            display("publisher: measurement no. " + i + " published, estimated lag: " + lag);
        }
        // close() sinaliza o fim do stream aos assinantes: seu método onComplete será chamado
        display("publisher: end of publication");
        publisher.close();
        // esperamos o arquivo ter processado tudo
        archive.end.await();
    }
}

// um assinante que processa cada medição em [duration] ms e cancela a assinatura além de [threshold]
class Subscriber implements Flow.Subscriber<Measurement> {
    private final String name;
    private final long duration;
    private final double threshold;
    private Flow.Subscription subscription;
    final CountDownLatch end = new CountDownLatch(1);

    Subscriber(String name, long duration, double threshold) {
        this.name = name;
        this.duration = duration;
        this.threshold = threshold;
    }

    @Override
    public void onSubscribe(Flow.Subscription subscription) {
        this.subscription = subscription;
        // o assinante pede os valores um a um: é ele quem controla o ritmo
        subscription.request(1);
    }

    @Override
    public void onNext(Measurement measurement) {
        display("  " + name + " : received " + measurement);
        sleep(duration);
        if (measurement.value() >= threshold) {
            display("  " + name + " : threshold reached, unsubscribing");
            subscription.cancel();
        } else {
            subscription.request(1);
        }
    }

    @Override
    public void onError(Throwable e) {
        display("  " + name + " : error " + e);
        end.countDown();
    }

    @Override
    public void onComplete() {
        display("  " + name + " : end of the stream");
        end.countDown();
    }
}

// Thread.sleep sem exceção verificada: uma interrupção vira uma CancellationException
void sleep(long ms) {
    try {
        Thread.sleep(ms);
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        throw new CancellationException("wait interrupted");
    }
}

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

// uma medição
record Measurement(String sensor, int number, double value) {
    @Override
    public String toString() {
        return sensor + " no. " + number + " : " + NumberFormat.getInstance().format(value) + " °C";
    }
}

Resultados:

> java Async20.java
  221 ms : publisher: measurement no. 1 published, estimated lag: 1
  269 ms :   archive : received sensor-1 no. 1 : 20.25 °C
  274 ms :   screen : received sensor-1 no. 1 : 20.25 °C
  466 ms : publisher: measurement no. 2 published, estimated lag: 2
  466 ms :   screen : received sensor-1 no. 2 : 21 °C
  667 ms :   screen : received sensor-1 no. 3 : 21.75 °C
  667 ms : publisher: measurement no. 3 published, estimated lag: 3
  770 ms :   archive : received sensor-1 no. 2 : 21 °C
  867 ms : publisher: measurement no. 4 published, estimated lag: 3
  868 ms :   screen : received sensor-1 no. 4 : 22.5 °C
  868 ms :   screen : threshold reached, unsubscribing
 1271 ms :   archive : received sensor-1 no. 3 : 21.75 °C
 1271 ms : publisher: measurement no. 5 published, estimated lag: 3
 1771 ms :   archive : received sensor-1 no. 4 : 22.5 °C
 1772 ms : publisher: measurement no. 6 published, estimated lag: 3
 1772 ms : publisher: end of publication
 2274 ms :   archive : received sensor-1 no. 5 : 23.25 °C
 2775 ms :   archive : received sensor-1 no. 6 : 24 °C
 3276 ms :   archive : end of the stream

Comentários:

  • linhas 26–70: o assinante, que processa cada medição em [duration] milissegundos e cancela a assinatura quando a medição atinge [threshold]:
    • linhas 40–45: [onSubscribe] recebe a assinatura e solicita um valor inicial;
    • linhas 47–57: [onNext] processa um valor e depois solicita outro ([request(1)]) ou encerra a assinatura ([cancel()]). Ao solicitar os valores um de cada vez, o assinante controla ele mesmo a taxa de dados;
    • linhas 59–69: [onError] e [onComplete] sinalizam o fim do stream, seja por um erro, seja normalmente. [CountDownLatch] permite que o programa principal espere esse fim;
  • linha 9: o publicador entrega os valores a cada assinante por meio de uma tarefa do executor especificado — neste caso, threads virtuais (sem um executor, ele usaria o pool compartilhado, em que a espera do arquivo bloquearia uma de suas poucas threads) — e mantém um buffer de até 2 valores para cada assinante;
  • linhas 12–17: o publicador publica uma medição a cada 200 ms usando [submit], que retorna uma estimativa do atraso: o maior número de valores publicados mas ainda não consumidos por um assinante. Quando o buffer de um assinante está cheio, [submit] espera que uma vaga fique disponível: a medição nº 5, pronta por volta de 1.070 ms, só é publicada em 1.271 ms (linha 14 dos resultados), quando o arquivo terminou de processar a medição nº 3. Isso é a contrapressão: o publicador é desacelerado ao ritmo do assinante mais lento. ([SubmissionPublisher] também oferece [offer], que permite descartar um valor em vez de esperar);
  • os resultados mostram que a tela, que é rápida, processa cada medição assim que ela é publicada e cancela a assinatura na medição nº 4 (22,5 °C, linhas 11–12), enquanto o arquivo, que leva 500 ms por medição, fica para trás e recebe as seis medições;
  • linhas 18–22: [close()] sinaliza o fim do stream: cada assinante ainda inscrito receberá [onComplete] após processar os valores de seu buffer (linha 20). O programa espera o fim do arquivo com a mensagem [CountDownLatch].

O modelo push é adequado para fontes que produzem dados em seu próprio ritmo (sensores, eventos, mensagens) e para cadeias de processamento reativo; o modelo pull, que é mais simples de escrever e de ler, é adequado para a leitura de uma fonte sob demanda. Com threads virtuais, o modelo pull costuma bastar.

9.10. Cache, voltar à thread correta e concluir a operação manualmente

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

Um [CompletableFuture] é um objeto: cada chamada a um método que retorna um aloca pelo menos um objeto no heap, que o coletor de lixo deve recuperar. Isso é desprezível para uma E/S que dura milissegundos, e os coletores de lixo atuais da JVM tratam objetos de vida curta de forma muito eficiente: Java não tem uma variante "leve" de [CompletableFuture] (outras linguagens têm, para métodos assíncronos chamados milhões de vezes que, na maioria das vezes, já têm seu resultado).

Para um método assíncrono que muitas vezes já tem o resultado, a boa prática é colocar em cache [CompletableFuture] os próprios objetos: um valor já conhecido é retornado por um [CompletableFuture] já concluído, sem nova alocação, e várias requisições concorrentes pelo mesmo valor compartilham a mesma operação em andamento. O programa [Async21.java] aplica isso a um serviço de taxas de câmbio:

// um cache de CompletableFutures: uma operação assíncrona que, na maioria das vezes, já tem o resultado
void main() {
    var service = new RateService();
    // 1 - leituras sucessivas: somente a primeira leitura de uma moeda consulta o servidor
    for (String code : List.of("EUR", "USD", "EUR", "EUR", "USD", "GBP", "EUR")) {
        long readingStart = System.nanoTime();
        BigDecimal rate = service.readRate(code).join();
        IO.println(String.format("%s : %6s read in %3d ms", code, NumberFormat.getInstance().format(rate),
                (System.nanoTime() - readingStart) / 1_000_000));
    }
    IO.println("1 - server accesses: " + service.nbServerAccesses() + ", readings: " + service.nbReadings());

    // 2 - três leituras simultâneas da mesma moeda: elas compartilham a mesma operação
    List<CompletableFuture<BigDecimal>> readings = List.of(
            service.readRate("CHF"), service.readRate("CHF"), service.readRate("CHF"));
    IO.println("2 - same object: " + (readings.get(0) == readings.get(2))
            + ", rate: " + NumberFormat.getInstance().format(readings.get(0).join())
            + ", server accesses: " + service.nbServerAccesses() + ", readings: " + service.nbReadings());

    // 3 - uma operação que falhou não é mantida no cache
    try {
        service.readRate("XYZ").join();
    } catch (CompletionException e) {
        IO.println("3 - " + e.getCause().getMessage() + ", cached currencies: " + service.cachedCurrencies());
    }
}

class RateService {
    // o cache contém os próprios CompletableFutures, concluídos ou em andamento
    private final Map<String, CompletableFuture<BigDecimal>> cache = new ConcurrentHashMap<>();
    private final AtomicInteger nbServerAccesses = new AtomicInteger();
    private final AtomicInteger nbReadings = new AtomicInteger();

    CompletableFuture<BigDecimal> readRate(String code) {
        nbReadings.incrementAndGet();
        // se a moeda estiver no cache, retornamos o CompletableFuture existente: nenhum objeto é criado
        return cache.computeIfAbsent(code, this::readRateFromServer);
    }

    private CompletableFuture<BigDecimal> readRateFromServer(String code) {
        nbServerAccesses.incrementAndGet();
        // simula a consulta a um servidor remoto (300 ms)
        CompletableFuture<BigDecimal> reading = new CompletableFuture<Void>()
                .completeOnTimeout(null, 300, TimeUnit.MILLISECONDS)
                .thenApply(nothing -> switch (code) {
                    case "EUR" -> BigDecimal.ONE;
                    case "USD" -> new BigDecimal("1.17");
                    case "GBP" -> new BigDecimal("0.87");
                    case "CHF" -> new BigDecimal("0.94");
                    default -> throw new IllegalArgumentException("unknown currency: " + code);
                });
        // em caso de falha, removemos a operação do cache para que uma leitura posterior seja tentada de novo
        return reading.whenComplete((rate, e) -> {
            if (e != null) {
                cache.remove(code);
            }
        });
    }

    int nbServerAccesses() {
        return nbServerAccesses.get();
    }

    int nbReadings() {
        return nbReadings.get();
    }

    Set<String> cachedCurrencies() {
        return new TreeSet<>(cache.keySet());
    }
}

Resultados:

> java Async21.java
EUR :      1 read in 363 ms
USD :   1.17 read in 300 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, readings: 7
2 - same object: true, rate: 0.94, server accesses: 4, readings: 10
3 - unknown currency: XYZ, cached currencies: [CHF, EUR, GBP, USD]

Comentários:

  • linha 30: o cache associa cada código de moeda ao [CompletableFuture] 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, a thread do timer que conclui as leituras);
  • Linhas 34–38: [computeIfAbsent(key, function)] retorna o valor associado à chave, se existir; caso contrário, chama a função, armazena seu resultado no dicionário e o retorna. Em um [ConcurrentHashMap], essa operação é atômica: duas threads que solicitam simultaneamente uma moeda ausente provocam apenas um único acesso ao servidor;
  • linhas 40–58: a consulta simulada ao servidor (300 ms). A continuação [thenApply] contém uma expressão [switch] sobre uma string, cujo ramo [default] lança uma exceção para uma moeda desconhecida;
  • linhas 52–57: em caso de falha, a operação é removida do cache para que uma requisição posterior pela mesma moeda consulte o servidor novamente, em vez de retornar indefinidamente a mesma falha. É o [CompletableFuture] retornado por [whenComplete] que é armazenado no cache: ele só é concluído depois que a ação foi executada, o que garante ao chamador que o cache está atualizado quando ele recebe o resultado;
  • linhas 5–11: para o chamador, nada muda: ele espera o resultado com [join()]. Os resultados mostram os três acessos ao servidor (300 ms cada; um pouco mais para o primeiro, durante o qual a JVM carrega as classes necessárias) e as quatro respostas imediatas vindas do cache;
  • linhas 13–18: três requisições simultâneas pela taxa de câmbio do franco suíço obtêm o mesmo objeto e resultam em apenas um acesso ao servidor (linha 10 dos resultados);
  • linhas 20–25: a moeda desconhecida resultou em uma falha e não está mais no cache (linha 11).

9.10.2. Voltando à thread da GUI

O programa [Async06.java] demonstrou que uma continuação é executada, conforme o caso, pela thread que conclui a operação ou por uma thread do executor selecionado. Em uma aplicação gráfica (Swing, JavaFX), isso importa: um componente gráfico só pode ser manipulado pela thread da interface. Java não tem nenhum mecanismo que devolva automaticamente o restante do código a essa thread; cabe ao programa solicitá-lo, seja passando o executor correto à continuação, seja usando as ferramentas da biblioteca gráfica:

  • com Swing, *[SwingUtilities.invokeLater(action)] faz a ação ser executada pela thread da interface; a referência de método [SwingUtilities::invokeLater] pode servir de executor para uma continuação: [download.thenAcceptAsync(page -> textArea.setText(page), SwingUtilities::invokeLater)]******. A classe [SwingWorker] também fornece um método, [doInBackground], que é executado por uma thread em segundo plano, e os métodos [process] e [done]*, que são executados pela thread da interface;
  • com JavaFX, [Platform.runLater(action)] serve ao mesmo propósito, e as classes [Task] e [Service] de [javafx.concurrent] encapsulam um processamento em segundo plano junto com seu progresso.

Em todos os casos, a regra é a mesma: a thread da interface nunca deve esperar ([join()], [get()], E/S bloqueante), caso contrário a janela congela. A tarefa de longa duração é executada por outra thread (uma thread virtual, por exemplo), e somente a atualização final dos componentes fica a cargo da thread da interface.

9.10.3. Concluindo um CompletableFuture manualmente

À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 [CompletableFuture]. Vimos a técnica com [Async17.java]: criar um [CompletableFuture] "pendente" usando seu construtor, retorná-lo imediatamente e concluí-lo você mesmo quando necessário:

  • [complete(value)] conclui-o com sucesso;
  • [completeExceptionally(exception)] conclui-o com falha;
  • [cancel(false)] cancela-o.

Esses três métodos não têm efeito se o [CompletableFuture] já tiver sido concluído ([complete] e [completeExceptionally] produzem então [false]): o primeiro a concluí-lo vence, o que resolve naturalmente situações de disputa (como um resultado e um timeout chegando ao mesmo tempo). O programa [Async22.java] espera que um termômetro — que notifica seus listeners a cada medição — atinja certa temperatura:

// um CompletableFuture concluído "à mão": transformando uma API baseada em listeners em uma operação assíncrona
final long start = System.nanoTime();

void main() {
    var thermometer = new Thermometer();
    thermometer.start();

    // 1 - esperamos a primeira medida maior ou igual a 21 °C
    double measure = waitForTemperature(thermometer, 21).join();
    display("1 - temperature reached: " + format(measure) + " °C");

    // 2 - a mesma espera, limitada a um segundo
    try {
        measure = waitForTemperature(thermometer, 30).orTimeout(1, TimeUnit.SECONDS).join();
        display("2 - temperature reached: " + format(measure) + " °C");
    } catch (CompletionException e) {
        display("2 - 30 °C not reached in one second: " + e.getCause().getClass().getSimpleName());
    }
    thermometer.stop();
}

// transforma as notificações do termômetro em um CompletableFuture
CompletableFuture<Double> waitForTemperature(Thermometer thermometer, double threshold) {
    // um CompletableFuture que nós mesmos concluiremos
    CompletableFuture<Double> result = new CompletableFuture<>();
    // o listener conclui o CompletableFuture quando o limite é atingido
    DoubleConsumer listener = temperature -> {
        if (temperature >= threshold) {
            result.complete(temperature);
        }
    };
    thermometer.addListener(listener);
    // seja qual for a forma como termina (limite, timeout, cancelamento), removemos o listener
    result.whenComplete((temperature, e) -> thermometer.removeListener(listener));
    // o CompletableFuture é retornado imediatamente; ele será concluído mais tarde
    return result;
}

// um termômetro que notifica seus listeners a cada 200 ms (uma API "à moda antiga")
class Thermometer {
    private final List<DoubleConsumer> listeners = new CopyOnWriteArrayList<>();
    private final ScheduledExecutorService timer = Executors.newSingleThreadScheduledExecutor();
    private double temperature = 19;

    void addListener(DoubleConsumer listener) {
        listeners.add(listener);
    }

    void removeListener(DoubleConsumer listener) {
        listeners.remove(listener);
    }

    void start() {
        timer.scheduleAtFixedRate(() -> {
            temperature += 0.5;
            IO.println("          measure: " + format(temperature) + " °C");
            listeners.forEach(listener -> listener.accept(temperature));
        }, 200, 200, TimeUnit.MILLISECONDS);
    }

    void stop() {
        timer.shutdown();
    }
}

// um número real no formato local, sem casas decimais inúteis
String format(double value) {
    return NumberFormat.getInstance().format(value);
}

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

Resultados:

> java Async22.java
          measure: 19.5 °C
          measure: 20 °C
          measure: 20.5 °C
          measure: 21 °C
  807 ms : 1 - temperature reached: 21 °C
          measure: 21.5 °C
          measure: 22 °C
          measure: 22.5 °C
          measure: 23 °C
          measure: 23.5 °C
 1809 ms : 2 - 30 °C not reached in one second: TimeoutException

Comentários:

  • Linhas 39–64: 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 [DoubleConsumer] (um [Consumer] especializado no tipo [double]). A lista de listeners é um [CopyOnWriteArrayList], uma lista que pode ser modificada por uma thread (adição ou remoção de um listener) enquanto outra thread a percorre;
  • linhas 22–37: o método que converte notificações em um [CompletableFuture]. Ele cria um [CompletableFuture<Double>] temporário, registra um listener no termômetro e retorna imediatamente o [CompletableFuture], que ainda não está concluído;
  • linhas 27–31: a cada medição, o listener verifica o limite. Quando ele é atingido, conclui o [CompletableFuture] com a temperatura como resultado. As medições seguintes continuam a chamar [complete], sem efeito, até que o listener seja removido;
  • linha 34: independentemente de como o [CompletableFuture] termine (limite atingido, timeout, cancelamento pelo chamador), [whenComplete] remove o listener. Sem isso, um listener cujo limite nunca fosse atingido permaneceria registrado indefinidamente;
  • Linhas 8–18: para o chamador, esperar por uma temperatura é uma operação assíncrona como qualquer outra: o chamador a espera com [join()] e define um limite de tempo para ela com [orTimeout]. Como [orTimeout] encerra o próprio [CompletableFuture] (e não uma cópia), a ação [whenComplete] da linha 34 é executada e o listener é removido.

Um aviso: as continuações anexadas a [CompletableFuture] são executadas pela thread que chama [complete] — neste caso, a thread do termômetro — no meio da notificação de seus listeners. Se essas continuações forem demoradas, elas devem ser escritas com as variantes [xxxAsync] e um executor, ou o [CompletableFuture] deve ser concluído com [completeAsync(() -> value, executor)] (Java 9), que faz o executor chamar [complete].

9.11. Paralelismo limitado

9.11.1. Threads virtuais e semáforos

[allOf] e uma thread virtual por operação lançam todas as operações simultaneamente. Nem sempre isso é desejável: para baixar 10.000 páginas web, você não quer abrir 10.000 conexões simultâneas com o mesmo servidor. Com threads de plataforma, a concorrência era limitada pelo tamanho do pool de threads. Com threads virtuais, as threads não são reunidas em pool (elas são tão baratas que se cria uma por tarefa): o acesso ao recurso escasso é limitado usando um [Semaphore] (Capítulo 8), cujas permissões representam o número de operações concorrentes permitidas. O programa [Async23.java] baixa nove páginas, no máximo três por vez:

// processamento de uma coleção com um número limitado de operações simultâneas: threads virtuais e Semaphore
final AtomicInteger inProgress = new AtomicInteger();

long start;

void main() {
    start = System.nanoTime();
    List<String> pages = IntStream.rangeClosed(1, 9).mapToObj(i -> "page" + i + ".html").toList();
    // no máximo 3 downloads ao mesmo tempo: um semáforo com 3 permissões
    var permits = new Semaphore(3);
    try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
        // uma thread virtual por página: elas são baratas, podemos criar tantas quantas forem as páginas
        for (String page : pages) {
            executor.submit(() -> {
                // a thread espera uma permissão (sem bloquear uma thread carrier)
                permits.acquire();
                try {
                    download(page);
                } finally {
                    permits.release();
                }
                return null;
            });
        }
    } // close() espera o fim de todos os downloads
    display("the " + pages.size() + " pages are downloaded");
}

void download(String page) throws InterruptedException {
    // contador compartilhado pelas operações simultâneas: nós o modificamos de forma atômica
    int n = inProgress.incrementAndGet();
    display("start of " + page + " (" + n + " in progress)");
    // o download simulado de uma página
    Thread.sleep(1000);
    inProgress.decrementAndGet();
    display("end of " + page);
}

// exibição com o tempo decorrido desde o início e a thread que executa a exibição
void display(String message) {
    Thread thread = Thread.currentThread();
    String name = thread.isVirtual() ? "virtual #" + thread.threadId() : thread.getName();
    IO.println(String.format("%5d ms [%-11s] : %s", (System.nanoTime() - start) / 1_000_000, name, message));
}

Resultados:

> java Async23.java
   13 ms [virtual #25] : start of page2.html (2 in progress)
   13 ms [virtual #27] : start of page3.html (3 in progress)
   13 ms [virtual #23] : start of page1.html (1 in progress)
 1026 ms [virtual #25] : end of page2.html
 1026 ms [virtual #27] : end of page3.html
 1026 ms [virtual #23] : end of page1.html
 1026 ms [virtual #28] : start of page4.html (1 in progress)
 1027 ms [virtual #29] : start of page5.html (2 in progress)
 1027 ms [virtual #30] : start of page6.html (3 in progress)
 2027 ms [virtual #29] : end of page5.html
 2027 ms [virtual #30] : end of page6.html
 2028 ms [virtual #31] : start of page7.html (1 in progress)
 2028 ms [virtual #32] : start of page8.html (2 in progress)
 2027 ms [virtual #28] : end of page4.html
 2028 ms [virtual #33] : start of page9.html (3 in progress)
 3028 ms [virtual #31] : end of page7.html
 3028 ms [virtual #32] : end of page8.html
 3029 ms [virtual #33] : end of page9.html
 3030 ms [main       ] : the 9 pages are downloaded

Comentários:

  • linha 10: um semáforo com 3 permissões;
  • linhas 13–24: uma thread virtual por página. A tarefa é uma lambda que termina com [return null;]: trata-se, portanto, de um [Callable], cujo método pode lançar exceções verificadas, o que evita ter de tratar a [InterruptedException], [acquire] e [Thread.sleep] aqui;
  • Linhas 16–21: cada thread espera uma permissão ([acquire]), baixa sua página e depois devolve a permissão ([release]) em um [finally], de modo que ela seja devolvida mesmo que o download falhe. Uma thread virtual que espera por uma autorização é desanexada de sua thread hospedeira, como durante uma operação de E/S;
  • Linhas 29–37: o contador [inProgress], compartilhado pelas threads, é uma versão modificada atomicamente de [AtomicInteger];
  • Os resultados mostram três ondas de três páginas: assim que uma página termina, outra começa, e o número de downloads em andamento nunca excede 3. O processo inteiro leva 3 segundos em vez de 9. Quando duas threads escrevem quase ao mesmo tempo, a ordem das linhas pode variar de uma execução para outra, e um horário exibido pode até ser ligeiramente anterior ao da linha anterior;
  • cada página tem sua própria thread virtual (nºs 23 a 33; os números são compartilhados por todas as threads da JVM, inclusive as threads portadoras, daí as lacunas), mas essas nove threads virtuais foram executadas pelas únicas duas threads portadoras da máquina.

9.11.2. Produtores / consumidores: BlockingQueue

O capítulo anterior apresentou o modelo produtor/consumidor: os produtores colocam itens em uma fila, e os consumidores os retiram. A interface [BlockingQueue<E>] é a ferramenta para isso: [put] coloca um item na fila e espera — se a fila for limitada e estiver cheia — que uma vaga fique disponível; [take] remove um elemento e espera — se a fila estiver vazia — que um chegue; [offer] e [poll] tentam fazer o mesmo sem esperar (ou com um prazo). Essas esperas são bloqueantes; quando executadas por threads virtuais, elas não bloqueiam nenhuma thread do sistema, e a fila bloqueante torna-se a ferramenta de comunicação entre operações assíncronas.

O programa [Async24.java] tem pedidos — gerados a cada 50 ms — processados por dois consumidores, cada um dos quais leva 400 ms para processar um pedido:

// produtor / consumidores com uma fila bloqueante, executados por threads virtuais
// o valor que sinaliza aos consumidores que não haverá mais pedidos
static final int END = -1;
// uma fila limitada: ela guarda no máximo 2 pedidos aguardando processamento
final BlockingQueue<Integer> queue = new ArrayBlockingQueue<>(2);
long start;

void main() {
    start = System.nanoTime();
    // o produtor e dois consumidores trabalham ao mesmo tempo
    try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
        executor.submit(() -> produce(8));
        executor.submit(() -> consume("C1"));
        executor.submit(() -> consume("C2"));
    }
    display("all the orders have been processed");
}

// o produtor: um pedido a cada 50 ms
Void produce(int nbOrders) throws InterruptedException {
    for (int i = 1; i <= nbOrders; i++) {
        Thread.sleep(50);
        // offer coloca o pedido imediatamente se houver espaço na fila
        if (queue.offer(i)) {
            display("P  : order " + i + " queued");
        } else {
            // fila cheia: put espera que uma vaga seja liberada
            display("P  : queue full, order " + i + " waits");
            queue.put(i);
            display("P  : order " + i + " queued");
        }
    }
    // nada mais será produzido: colocamos o marcador de fim
    queue.put(END);
    display("P  : end of production");
    return null;
}

// um consumidor: processar um pedido leva 400 ms
Void consume(String name) throws InterruptedException {
    while (true) {
        // take espera até que haja um pedido na fila
        int order = queue.take();
        if (order == END) {
            // colocamos o marcador de fim de volta na fila para o outro consumidor
            queue.put(END);
            break;
        }
        display(name + " : processing of order " + order);
        Thread.sleep(400);
    }
    display(name + " : no more orders");
    return null;
}

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

Resultados:

> java Async24.java
   58 ms : P  : order 1 queued
   62 ms : C1 : processing of order 1
  118 ms : C2 : processing of order 2
  119 ms : P  : order 2 queued
  169 ms : P  : order 3 queued
  220 ms : P  : order 4 queued
  271 ms : P  : queue full, order 5 waits
  469 ms : P  : order 5 queued
  469 ms : C1 : processing of order 3
  519 ms : C2 : processing of order 4
  519 ms : P  : order 6 queued
  570 ms : P  : queue full, order 7 waits
  870 ms : C1 : processing of order 5
  870 ms : P  : order 7 queued
  920 ms : C2 : processing of order 6
  920 ms : P  : order 8 queued
 1270 ms : C1 : processing of order 7
 1271 ms : P  : end of production
 1320 ms : C2 : processing of order 8
 1672 ms : C1 : no more orders
 1721 ms : C2 : no more orders
 1721 ms : all the orders have been processed

Comentários:

  • linha 5: uma [ArrayBlockingQueue] com capacidade 2: ela contém no máximo 2 pedidos pendentes;
  • Linhas 11–15: o produtor e os dois consumidores são executados por três threads virtuais; o programa espera o fim das três usando o método [close()] do executor. Os métodos [produce] e [consume] retornam [Void] e terminam com [return null;]: as lambdas das linhas 12–14 são, portanto, [Callable], e os métodos podem declarar [InterruptedException];
  • Linhas 19–37: o produtor tenta submeter cada pedido usando [offer]. Se a fila estiver cheia, ele sinaliza isso e espera por espaço usando [put]: o produtor é desacelerado ao ritmo dos consumidores (linhas 8–9 dos resultados). Este é o benefício de uma fila limitada: um produtor rápido demais não consegue encher a memória;
  • linha 34: a produção terminou; o produtor coloca um valor específico, o marcador de fim [END] (linha 3), que os consumidores reconhecerão. Uma fila bloqueante, de fato, não tem como sinalizar que está "fechada";
  • Linhas 39–54: cada consumidor retira pedidos com [take]. Um pedido é entregue a apenas um consumidor: os pedidos são distribuídos entre C1 e C2 conforme a disponibilidade deles. O consumidor que recebe o marcador de fim o coloca de volta na fila para o outro consumidor e depois para;
  • como no exemplo anterior, duas linhas exibidas quase ao mesmo tempo podem aparecer fora de ordem.

9.12. Tempo: ScheduledExecutorService e Clock

Duas ferramentas complementam as relacionadas ao tempo:

  • um [ScheduledExecutorService] (Java 5) é um executor capaz de executar uma tarefa após um atraso ([schedule]) ou periodicamente ([scheduleAtFixedRate], em intervalos fixos medidos do início de uma execução ao início da seguinte; [scheduleWithFixedDelay], com um atraso fixo entre o fim de uma execução e o início da seguinte). Uma tarefa periódica nunca é executada duas vezes ao mesmo tempo: se uma execução demorar mais que o período, a seguinte é adiada. Um executor de thread única é obtido com [Executors.newSingleThreadScheduledExecutor()];
  • a classe abstrata [java.time.Clock] (Java 8) representa o relógio: ela fornece a hora atual e o fuso horário. [Clock.systemDefaultZone()] é o relógio do sistema no fuso horário da máquina. Todos os métodos [now()] da API [java.time] ([LocalDateTime.now(clock)], [Instant.now(clock)]…) aceitam um relógio. Uma classe que depende do tempo recebe um [Clock] em vez de chamar [LocalDateTime.now()]: ela pode então ser testada com um relógio controlado.

O programa [Async25.java] usa as duas:

// tempo: ScheduledExecutorService e Clock
void main() throws InterruptedException {
    // 1 - uma ação a cada 500 ms, interrompida após 2,2 segundos
    long start = System.nanoTime();
    AtomicInteger nbTicks = new AtomicInteger();
    try (ScheduledExecutorService scheduler = Executors.newSingleThreadScheduledExecutor()) {
        // scheduleAtFixedRate: primeiro tick em 500 ms, depois um tick a cada 500 ms
        ScheduledFuture<?> ticks = scheduler.scheduleAtFixedRate(
                () -> IO.println(String.format("%6d ms : tick no. %d",
                        (System.nanoTime() - start) / 1_000_000, nbTicks.incrementAndGet())),
                500, 500, TimeUnit.MILLISECONDS);
        // schedule: uma única ação, em 2,2 segundos, que interrompe os ticks
        ScheduledFuture<?> stop = scheduler.schedule(
                () -> ticks.cancel(false), 2200, TimeUnit.MILLISECONDS);
        stop.get();
        IO.println(String.format("%6d ms : timer stopped after %d ticks",
                (System.nanoTime() - start) / 1_000_000, nbTicks.get()));
    } catch (ExecutionException e) {
        IO.println("error: " + e.getCause());
    }

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

// uma classe que depende da hora atual
record Reception(Clock clock) {
    String greet(String name) {
        LocalDateTime now = LocalDateTime.now(clock);
        String greeting = now.getHour() < 18 ? "Hello" : "Good evening";
        String date = now.format(DateTimeFormatter.ofPattern("dd/MM/yyyy HH:mm"));
        return "[" + date + "] " + greeting + " " + name;
    }
}

Resultados:

1
2
3
4
5
6
7
8
9
> java Async25.java
   504 ms : tick no. 1
  1003 ms : tick no. 2
  1503 ms : tick no. 3
  2003 ms : tick no. 4
  2204 ms : timer stopped after 4 ticks
[03/10/2026 09:30] Hello Pierre
[03/10/2026 19:45] Good evening Pierre
[03/10/2026 19:18] Good evening Pierre (system clock)

Comentários:

  • Linhas 8–11: [scheduleAtFixedRate(task, initialDelay, period, unit)] executa a tarefa pela primeira vez após 500 ms e depois a cada 500 ms. Ele retorna um [ScheduledFuture] e um [Future], o que, entre outras coisas, permite cancelar execuções futuras. O contador de tops é um [AtomicInteger]: uma lambda não pode modificar uma variável local;
  • Linhas 13–15: [schedule(task, delay, unit)] executa uma única tarefa após 2,2 segundos: ela cancela os tops. [stop.get()] espera essa tarefa terminar. Os bipes ocorreram em 0,5, 1, 1,5 e 2 segundos, e o timer para em 2,2 segundos, após 4 bipes;
  • linhas 30–38: o record [Reception] diz "Hello" ou "Good evening" conforme a hora. Ele recebe seu relógio pelo construtor em vez de chamar [LocalDateTime.now()]: esta é uma dependência injetada, assim como a camada [dao] é injetada na camada [business] no Capítulo 6;
  • Linhas 23–27: [Clock.fixed(instant, zone)] retorna um relógio parado que sempre mostra a mesma hora; isso nos permite verificar o comportamento de [Reception] de manhã e à noite sem precisar esperar até a noite. A última linha usa o relógio do sistema (portanto o resultado depende da hora de execução). Para testes mais sofisticados, você pode escrever sua própria classe derivada de [Clock], que você possa avançar como quiser. A interface [InstantSource] (Java 17), que retorna apenas a hora atual, é uma dependência ainda mais leve quando o fuso horário é irrelevante.

Para medir uma duração, não use o relógio (que pode ser ajustado durante a medição, por exemplo, pela sincronização da hora do sistema), mas use [System.nanoTime()], como mostrado nos exemplos deste capítulo.

9.13. Concorrência estruturada (visão geral)

Nos exemplos anteriores, as operações lançadas por um programa são executadas de forma independente dele: se uma falha, as outras continuam; se o código que as lançou é interrompido, elas também continuam; e nada obriga esse código a esperar o término delas. A concorrência estruturada propõe tratar um grupo de subtarefas como um único bloco: elas são lançadas dentro de um escopo, o escopo espera que todas terminem e, se uma falhar, as outras são canceladas. A classe [StructuredTaskScope] implementa essa ideia usando threads virtuais. Ela está disponível desde o Java 21, mas ainda está em “preview” (prévia) 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]. Por isso, ela não é incluída nos exercícios do curso; o código a seguir (arquivo [preview/StructuredConcurrency.txt], a ser copiado para um arquivo chamado [StructuredConcurrency.java] para testá-lo) dá uma ideia de como ela funciona:

// concorrência estruturada: API em 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:

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

Comentários:

  • linha 8: [StructuredTaskScope.open()] abre um escopo, declarado em um [try] com recurso; seu fechamento garante que nenhuma subtarefa sobreviva a ele;
  • Linhas 9–10: [fork] lança uma subtarefa em uma nova thread virtual e retorna um [Subtask];
  • linha 13: [join()] espera o término de todas as subtarefas. Com a política padrão, se uma subtarefa falha, as outras são canceladas (abortadas) e [join()] lança uma exceção;
  • linha 14: os resultados das subtarefas, todas concluídas;
  • Linhas 17–21: outra política, fornecida por [Joiner]: a primeira subtarefa bem-sucedida fornece o resultado de [join()], e as outras são canceladas. É o equivalente estruturado de [anyOf], mas as requisições perdedoras são realmente encerradas.

9.14. Aplicação: cálculo do imposto com threads virtuais

O programa [Async26.java] reúne várias ferramentas deste capítulo relacionadas ao cálculo do imposto da thread principal. Ele lê as faixas de imposto do arquivo [TaxData.txt], já utilizado anteriormente, e lê uma lista de contribuintes do arquivo [taxpayers.txt]:

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 pessoa e grava os resultados no arquivo [results.txt]. As duas leituras são realizadas simultaneamente por threads virtuais, e todo o processo é limitado a 10 segundos.

// aplicação: o cálculo do imposto, com entrada / saída executada por threads virtuais
// - as faixas são lidas em [TaxData.txt], os contribuintes em [taxpayers.txt]
// - os resultados são escritos em [results.txt]
// uma linha de contribuinte correta: casado (y/n), número de filhos, salário anual
static final Pattern TAXPAYER = Pattern.compile("([yn])\\s+(\\d+)\\s+(\\d+)");

void main() {
    Path results = Path.of("results.txt");
    try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
        // os dois arquivos de entrada são lidos ao mesmo tempo, por duas threads virtuais
        Future<List<TaxBracket>> bracketsReading = executor.submit(
                () -> loadBrackets(Path.of("TaxData.txt")));
        Future<List<String>> taxpayersReading = executor.submit(
                () -> Files.readAllLines(Path.of("taxpayers.txt")));
        // o cálculo espera as duas leituras e depois escreve os resultados
        Future<Integer> processing = executor.submit(
                () -> calculateTaxes(bracketsReading.get(), taxpayersReading.get(), results));
        try {
            // todo o processamento é limitado a 10 segundos
            int nbResults = processing.get(10, TimeUnit.SECONDS);
            IO.println(nbResults + " lines written in [" + results + "] :");
            IO.print(Files.readString(results));
        } catch (TimeoutException e) {
            processing.cancel(true);
            IO.println("processing abandoned: timeout exceeded");
        }
    } catch (ExecutionException e) {
        // o erro de uma leitura é encapsulado duas vezes: pela leitura e pelo cálculo que a esperou
        Throwable cause = e.getCause();
        while (cause instanceof ExecutionException) {
            cause = cause.getCause();
        }
        IO.println("error: " + cause.getClass().getSimpleName() + " : " + cause.getMessage());
    } catch (IOException | InterruptedException e) {
        IO.println("error: " + e.getClass().getSimpleName() + " : " + e.getMessage());
    }
}

// lê as faixas do imposto (limit:coeffR:coeffN, ponto decimal)
List<TaxBracket> loadBrackets(Path file) throws IOException {
    try (Stream<String> lines = Files.lines(file)) {
        return lines.filter(line -> !line.isBlank()).map(TaxBracket::parse).toList();
    }
}

// calcula o imposto de cada contribuinte e escreve os resultados
int calculateTaxes(List<TaxBracket> brackets, List<String> taxpayers, Path output) throws IOException {
    try (BufferedWriter writer = Files.newBufferedWriter(output)) {
        for (String line : taxpayers) {
            Matcher fields = TAXPAYER.matcher(line.trim());
            String result = fields.matches()
                    ? "tax = " + calculateTax(brackets, fields.group(1).equals("y"),
                            Integer.parseInt(fields.group(2)), Integer.parseInt(fields.group(3))) + " €"
                    : "incorrect line";
            writer.write(String.format("%-12s : %s", line, result));
            writer.newLine();
        }
    }
    return taxpayers.size();
}

// o cálculo do imposto (tabela de 2004 sobre a renda de 2003, mantida para o exercício)
int calculateTax(List<TaxBracket> brackets, boolean married, int nbChildren, int salary) {
    BigDecimal shares = BigDecimal.valueOf(nbChildren).divide(BigDecimal.TWO)
            .add(BigDecimal.valueOf(married ? 2 : 1));
    if (nbChildren >= 3) {
        shares = shares.add(new BigDecimal("0.5"));
    }
    BigDecimal income = new BigDecimal("0.72").multiply(BigDecimal.valueOf(salary));
    BigDecimal quotient = income.divide(shares, MathContext.DECIMAL64);
    // a primeira faixa cujo limite excede o quociente familiar, caso contrário a última
    TaxBracket bracket = brackets.stream()
            .filter(t -> quotient.compareTo(t.limit()) <= 0)
            .findFirst()
            .orElse(brackets.getLast());
    return bracket.coeffR().multiply(income).subtract(bracket.coeffN().multiply(shares)).intValue();
}

// uma faixa do imposto
record TaxBracket(BigDecimal limit, BigDecimal coeffR, BigDecimal coeffN) {
    static TaxBracket parse(String line) {
        String[] fields = line.split(":");
        return new TaxBracket(new BigDecimal(fields[0]), new BigDecimal(fields[1]),
                new BigDecimal(fields[2]));
    }
}

Resultados:

1
2
3
4
5
6
7
8
9
> java Async26.java
7 lines written in [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

O mesmo programa, executado em uma pasta em que o arquivo [TaxData.txt] está ausente:

> java Async26.java
error: NoSuchFileException : TaxData.txt

Comentários:

  • linhas 11–14: os dois arquivos de entrada são lidos simultaneamente por duas threads virtuais, usando métodos de leitura bloqueantes padrão ([Files.lines], [Files.readAllLines]);
  • linhas 16–17: o cálculo é uma terceira tarefa, que começa esperando o término das duas leituras com [get()]. Essas esperas bloqueiam uma thread virtual, o que não tem custo;
  • linhas 18–26: o programa principal espera o resultado por até 10 segundos. Depois disso, ele aborta o processo (o que encerra sua thread virtual) e relata o erro;
  • linhas 27–36: os erros são tratados em um único local do programa principal. Um erro de leitura (arquivo ausente, número incorreto) é armazenado no [Future] associado à operação de leitura; o [get()] do cálculo o relança em uma [ExecutionException], que por sua vez se torna a exceção do cálculo, relançada pelo [get] do programa principal em uma segunda [ExecutionException]. O laço das linhas 30–32 remonta à causa original (segundo resultado). Essa é a desvantagem das tarefas dependentes; a concorrência estruturada, descrita no parágrafo anterior, elimina esse problema;
  • linhas 39–44: leitura das faixas, usando um [Stream] que ignora as linhas vazias;
  • linhas 46–60: processamento dos contribuintes. Cada linha é validada pela expressão regular da linha 5: um [y] ou um [n], seguido de dois inteiros positivos separados por espaços ([\s+]). Os parênteses definem três grupos, que [group(1)], [group(2)], e [group(3)] retornam depois que [matches()] verifica que a linha inteira corresponde à expressão. Uma linha incorreta ([x] em vez de [y/n], salário negativo) é sinalizada como tal;
  • linhas 62–77: cálculo do imposto, em [BigDecimal]. A divisão da renda pelo número de cotas pode não ser exata: ela é feita com uma precisão de 16 dígitos significativos ([MathContext.DECIMAL64]). A primeira faixa de imposto cujo limite é maior ou igual ao quociente familiar é determinada por um stream; [orElse(brackets.getLast())] retorna a última faixa se nenhuma corresponder. [intValue()] arredonda o imposto para baixo, até o euro inteiro;
  • 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.

O cálculo em si é síncrono: ele não realiza E/S e leva alguns microssegundos. Seria inútil, e até prejudicial, transferi-lo para outra thread. Somente as tarefas que envolvem espera são tornadas assíncronas.

9.15. As regras de ouro

Vamos resumir as regras da programação assíncrona em Java:

  • para esperar, não bloqueie uma thread do sistema: uma espera (E/S, timeout ou outra operação) é realizada em uma thread virtual ou anexando uma continuação a um [CompletableFuture];
  • para código novo, prefira threads virtuais: escreva código bloqueante, sequencial e legível (laços, [try / catch], variáveis locais comuns), executado por [Executors.newVirtualThreadPerTaskExecutor()]; uma thread virtual por tarefa, nunca use um pool de threads virtuais;
  • use [CompletableFuture] para compor operações ou para usar uma API que retorna [CompletableFuture] ([HttpClient.sendAsync], bibliotecas reativas); escolhe-se então o executor das continuações ([xxxAsync(..., executor)]) e nunca se executa uma operação bloqueante no pool compartilhado;
  • nada de [join()] ou [get()] em uma continuação ou em uma thread de GUI: essas esperas bloqueiam a thread que as executa. Elas pertencem ao programa principal ou a uma thread virtual;
  • as threads virtuais servem para esperas, não para cálculos: para cálculos, use um pool de threads de plataforma dimensionado de acordo com o número de processadores, ou streams paralelos;
  • limite o acesso a recursos escassos usando um [Semaphore], e não pelo tamanho de um pool de threads;
  • o cancelamento é cooperativo: uma tarefa é cancelada por meio de [Future.cancel(true)], que interrompe sua thread; uma tarefa interrompida termina de forma elegante; uma [InterruptedException] nunca é mascarada (ela é propagada ou o sinalizador de interrupção é restaurado). E lembre-se de que [CompletableFuture.cancel] não interrompe nada;
  • limite os tempos de espera: [orTimeout], [completeOnTimeout], [get(timeout, unit)]; e encerre a própria operação se a espera for abandonada;
  • comece primeiro, espere depois: para executar várias operações independentes simultaneamente, inicie todas e só então espere por elas ([allOf], [invokeAll], o método [close] do executor);
  • uma operação lançada deve ser aguardada ou monitorada: uma operação esquecida oculta suas exceções ([exceptionally], [whenComplete] para tratá-las); ao remontar uma [CompletionException] ou uma [ExecutionException], buscamos a causa raiz.

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

Threads de plataforma, esperas bloqueantes
CompletableFuture
Threads virtuais
[Thread.sleep(1000)] (bloqueia a thread)
[new CompletableFuture<Void>().completeOnTimeout(null, 1, SECONDS)]
[Thread.sleep(1000)] (libera a thread portadora)
[thread.start()] seguido de [thread.join()]
[supplyAsync(...)] seguido de [join()] ou de uma continuação
[executor.submit(...)] seguido de [get()]
Esperar várias threads ([join] em um laço)
[allOf(...)], [anyOf(...)]
[invokeAll(...)], [ExecutorCompletionService], [close()]
Métodos de callback ([CompletionHandler])
[thenApply], [thenCompose], [thenCombine]
O código que segue a chamada bloqueante
[try / catch] em volta de [get()] ([ExecutionException])
[exceptionally], [handle], [whenComplete]
[try / catch] (padrão)
[thread.interrupt()]
[cancel(...)] (não interrompe nada)
[future.cancel(true)] (interrompe a thread)
[future.get(timeout, unit)]
[orTimeout(...)], [completeOnTimeout(...)]
[future.get(timeout, unit)]
pool de threads de tamanho fixo
executor das continuações [xxxAsync]
[Semaphore]
[BlockingQueue] (bloqueia a thread)
[Flow], [SubmissionPublisher]
[BlockingQueue] (libera a thread portadora)
[ScheduledExecutorService]
[completeOnTimeout], [delayedExecutor]
[Thread.sleep] em um laço

Os próximos capítulos aplicarão essas regras: acesso a bancos de dados usando JDBC (Capítulo 10) e Hibernate (Capítulo 11), cujas operações de API são bloqueantes e funcionam naturalmente com threads virtuais, o servidor TCP, que atende cada cliente por meio de uma thread virtual, e o cliente [HttpClient] (Capítulo 12); serviços web com Spring Boot, em que o servidor Tomcat pode processar cada requisição por meio de uma thread virtual; e seus clientes (Capítulo 13).