E aí, dev que já passou horas debugando um ThreadLocal que não foi limpo e vazou memória? Pois é. Esse velho conhecido do Java 1.2 sempre foi a solução para guardar dados "por thread" como o userId de uma requisição, ou uma conexão de banco que não pode ser compartilhada.

Mas aí chegaram as Virtual Threads no JDK 21, e o jogo mudou. Criar milhões de threads leves virou realidade, e o bom e velho ThreadLocal começou a mostrar suas fraquezas. A boa notícia? O Java 21 trouxe uma alternativa moderna e elegante: Scoped Values.

Vamos entender tudo isso com exemplos práticos. Bora? 🚀

🔍 O que é ThreadLocal (e por que você usava isso)?

ThreadLocal é uma classe que permite criar variáveis que só podem ser acessadas e modificadas pela mesma thread. Cada thread que acessa um ThreadLocal tem sua própria cópia independente da variável.

Exemplo clássico:

public class ContextoUsuario {
    private static final ThreadLocal<String> USER_ID = new ThreadLocal<>();

    public static void setUserId(String userId) {
        USER_ID.set(userId);
    }

    public static String getUserId() {
        return USER_ID.get();
    }

    public static void clear() {
        USER_ID.remove(); // 👈 NUNCA ESQUEÇA DISSO!
    }
}

// Em algum lugar do código...
ContextoUsuario.setUserId("alice123");
String user = ContextoUsuario.getUserId(); // "alice123"
ContextoUsuario.clear();

Use quando: precisar associar dados a uma thread específica sem passar parâmetros por toda a cadeia de chamadas tipo userId numa requisição web, conexão de banco, ou transação.

⚠️ Os problemas clássicos do ThreadLocal (que todo mundo já sofreu)

1. 💀 Memory Leak

Se você esquecer de chamar remove(), o valor fica preso na thread. Se a thread for reaproveitada (como num pool), o valor vaza e pode nunca ser coletado.

2. 🔄 Contaminação entre requisições

Num pool de threads, uma requisição pode "herdar" o ThreadLocal da requisição anterior, porque a thread foi reaproveitada. Resultado: usuário A vê dados do usuário B. Um pesadelo de segurança.

3. 🧪 Dificuldade de testar

O comportamento do ThreadLocal depende do contexto de execução da thread, o que torna os testes imprevisíveis e difíceis de controlar.

4. 🌍 Global state disfarçado

Embora sejam "locais à thread", múltiplas threads compartilham o mesmo código. O uso excessivo cria dependências escondidas que tornam o código difícil de entender.

🧵 O problema com Virtual Threads

Aqui a coisa fica séria.

Virtual threads são leves e descartáveis você pode criar milhões delas. Elas aparecem e desaparecem em frações de milissegundo.

O ThreadLocal, por sua vez, foi feito para threads longas e reutilizáveis. Com virtual threads, cada uma pode ter seu próprio ThreadLocal e, se você estiver armazenando objetos grandes, o heap pode explodir com milhões de cópias.

Além disso, se a virtual thread terminar e o ThreadLocal não for limpo, o valor pode continuar ocupando memória mesmo depois que a thread já morreu.

⚠️ Importante: Nas versões preview do JDK 19 e 20, era possível criar virtual threads sem suporte a ThreadLocal. No JDK 21, todas as virtual threads suportam ThreadLocal para garantir compatibilidade com bibliotecas existentes. Mas isso não significa que você deva usar significa que você precisa ter mais cuidado ainda.

✨ A novidade do Java 21: Scoped Values

O Java 21 trouxe os Scoped Values (JEP 446). A ideia é simples e elegante:

• Em vez de guardar dados dentro da thread (como o ThreadLocal), o ScopedValue prende o valor a um bloco de código.
• Quando o bloco termina, o valor some automaticamente sem remove(), sem memory leak.
• É imutável: uma vez bindado, não pode ser alterado.
• Funciona perfeitamente com virtual threads.

Exemplo com ScopedValue:

public class ContextoModerno {
    // Declara o ScopedValue (geralmente static final)
    private static final ScopedValue<String> USER_ID = ScopedValue.newInstance();

    public void processarRequisicao(String userId) {
        // "Amarra" o valor a um bloco de código
        ScopedValue.where(USER_ID, userId).run(() -> {
            // Dentro deste bloco, USER_ID.get() retorna "userId"
            System.out.println("Usuário: " + USER_ID.get());
            chamarOutroMetodo(); // O valor continua disponível
        });
        // Fora do bloco, USER_ID.get() lança exceção
    }

    private void chamarOutroMetodo() {
        // Ainda consegue acessar o valor aqui dentro
        String user = USER_ID.get();
        System.out.println("Método aninhado: " + user);
    }
}

O que acontece aqui?

• O valor userId fica disponível apenas dentro do bloco run() e em todos os métodos chamados a partir dele.
• Quando o bloco termina, o valor é automaticamente descartado.
• Nada de remove() o Java cuida de tudo.

📊 Comparativo rápido

🧭 Quando usar cada um?

✅ Use ThreadLocal se:

• Você está mantendo código legado que já usa ThreadLocal
• Precisa de um valor que realmente deve viver durante toda a vida da thread (ex: pool de conexões JDBC)
• Não está usando virtual threads (ou está usando platform threads tradicionais)

✅ Use ScopedValue se:

• Está no Java 21 ou superior
• Usa virtual threads (ou planeja usar)
• Precisa passar contexto (ex: userId, transactionId, tenantId) por uma cadeia de chamadas
• Quer código mais seguro, limpo e sem memory leak

❌ Evite ThreadLocal se:

• Está usando virtual threads e armazenando objetos grandes
• Não quer se preocupar com remove() e memory leak
• Quer código mais fácil de testar e entender

💡 Dica de ouro

Se você está no Java 21 e usando virtual threads, ScopedValue é o caminho. ThreadLocal ainda funciona, mas você vai pagar o preço em memória e complexidade.

E lembre-se: se for usar ThreadLocal em qualquer cenário, sempre envolva o uso com try-finally e chame remove() no finally. É feio, mas é necessário.

🎯 Conclusão

O ThreadLocal serviu bem por décadas, mas o mundo mudou. As virtual threads vieram para ficar, e com elas veio a necessidade de ferramentas mais modernas e seguras.

O ScopedValue não é só "um ThreadLocal melhor" é uma mudança de paradigma: dados atrelados a blocos de código, não a threads. Mais seguro, mais performático, mais fácil de raciocinar.

Da próxima vez que for guardar um userId ou um contexto de requisição, pergunte-se: estou no Java 21? Se sim, dê uma chance ao ScopedValue. Sua memória (e seu eu do futuro debugando) vão agradecer. 🧵✨

Já usou ScopedValue? Ou ainda sofre com ThreadLocal? Conta aí nos comentários! 👇

Java21 #VirtualThreads #ThreadLocal #ScopedValue #Concorrência

Quer mais? No próximo post vou mostrar como migrar um código real de ThreadLocal para ScopedValue num projeto Spring Boot. Até lá! 🚀