runBlocking — o que é, ponte bloqueante e como funciona

O que é runBlocking?

runBlocking é uma função Kotlin que cria um novo CoroutineScope e executa a corrotina passada, bloqueando a thread atual até sua conclusão completa. Ao contrário de todos os outros Coroutine Builders, runBlocking não é uma função suspend e pode ser chamado de código síncrono comum. A assinatura de runBlocking recebe um CoroutineContext e um bloco suspend, retornando um resultado do tipo T.

public fun <T> runBlocking(
    context: CoroutineContext = EmptyCoroutineContext,
    block: suspend CoroutineScope.() -> T
): T

runBlocking inicia um novo event-loop na thread atual. Quando a corrotina chama uma função suspend (por exemplo, delay() ou await()), runBlocking bloqueia a thread e executa outras corrotinas agendadas na mesma thread até que a suspensa seja retomada. Isso é bloqueio cooperativo — a thread não fica ociosa, mas processa outras corrotinas.

Como funciona o runBlocking

O mecanismo interno do runBlocking é baseado em um event-loop: ao chamar uma função suspend, o runBlocking pausa a execução do bloco atual e executa outras corrotinas da fila. Quando a função suspend é concluída, a execução é retomada. Este ciclo continua até que todas as corrotinas terminem.

Event-loop internamente

runBlocking usa seu próprio pool de thread única para executar corrotinas. Ao contrário de Dispatchers.IO ou Default, runBlocking não alterna threads — ele manipula todas as corrotinas na thread atual, intercalando sua execução. Este é o único builder que garante a execução na mesma thread.

fun main() {
    val threadName = Thread.currentThread().getName()
    println("Antes de runBlocking em $threadName")

    val result = runBlocking {
        println("Dentro de runBlocking em ${Thread.currentThread().getName()}")
        delay(500L)
        "Done"
    }

    println("Depois de runBlocking: $result")
}

A saída mostrará que todas as três instruções println são executadas na mesma thread. runBlocking não alterna threads, mas organiza multitarefa cooperativa dentro de uma única thread usando um event-loop.

Quando usar runBlocking

runBlocking é justificado em três cenários: o ponto de entrada main() em aplicações de console, testes unitários de funções suspend e ponte — chamar código suspend de bibliotecas baseadas em callbacks ou bloqueantes. Em código Android de produção, usá-lo na thread principal é estritamente proibido.

Para testes Android, use kotlinx-coroutines-test com TestDispatcher em vez de runBlocking. Isso dá controle de tempo, limpeza automática e isolamento de testes.

Alternativas ao runBlocking

Na maioria dos cenários, runBlocking pode e deve ser substituído por alternativas assíncronas. Para Android, são viewModelScope, lifecycleScope ou CoroutineScope com o dispatcher adequado. Para testes — TestCoroutineDispatcher e runTest.

    // Ruim: runBlocking na thread principal do Android
runBlocking(Dispatchers.Main) {
    val result = networkApi.fetchData()
    textView.setText(result)
}

// Bom: lifecycleScope
lifecycleScope.launch {
    val result = withContext(Dispatchers.IO) { networkApi.fetchData() }
    textView.setText(result)
}

Para testes, a substituição é runTest de kotlinx-coroutines-test. Ele cria um TestCoroutineScope com tempo virtual, permitindo testar atrasos sem espera real. Isso acelera os testes e os torna determinísticos.

Exemplos de uso do runBlocking

O cenário mais comum é testar funções suspend. runBlocking em testes permite aguardar sincronamente um resultado de corrotina sem alterar a arquitetura. O segundo cenário são bibliotecas com API de callbacks, onde funções suspend são chamadas de um contexto bloqueante via runBlocking.

// Testar função suspend com runBlocking
class RepositoryTest {
    @Test
    fun `fetchUser returns correct data`() {
        val repository = UserRepository(FakeApi())

        val result = runBlocking {
            repository.fetchUser("123")
        }

        assertEquals("John", result.name)
        assertEquals("john@test.com", result.email)
    }
}

Para a ponte entre callbacks e o mundo suspend, use CompletableDeferred em combinação com runBlocking em vez de callbacks — isso simplifica cadeias de operações assíncronas e melhora a legibilidade do código.

Perigos do uso incorreto

O uso inadequado de runBlocking é um dos erros comuns ao migrar de uma abordagem bloqueante para corrotinas. Principais problemas: chamada na thread principal do Android, aninhamento de runBlocking, uso dentro de funções assíncronas e execução de operações longas com runBlocking.

• ANR — runBlocking na thread principal do Android bloqueia a renderização da UI por mais de 5 segundos
• Deadlock — runBlocking aninhado dentro de uma corrotina na mesma thread leva a um bloqueio mútuo
• Confusão com dispatchers — Dispatchers.Main dentro de runBlocking em uma thread de background não tem Looper e lança exceção
• Vazamentos de memória — runBlocking não é cancelado automaticamente ao destruir Activity/Fragment

Regra de ouro: runBlocking é uma ponte, não uma substituição. Use-o apenas para conectar mundos bloqueantes e não bloqueantes. Para todas as outras tarefas, use launch, async ou lifecycleScope.