suspend function: o que é, sintaxe e funcionamento em corrotinas

O que é uma suspend function em Kotlin?

Suspend function é uma função declarada com a palavra-chave suspend que pode pausar a execução em um ou mais pontos sem bloquear a thread. Cada chamada a uma função suspend dentro de outra função suspend é um ponto de suspensão potencial.

suspend fun fetchUserData(): User {
    val response = httpClient.get("/user")
    return parser.parse(response)
}

O compilador Kotlin traduz essa função em uma máquina de estados. Cada ponto de suspensão (uma chamada a outra função suspend) torna-se um estado (label). A thread atual é liberada entre os estados e, quando a operação aguardada é concluída, a execução é retomada a partir do próximo estado.

História

As funções suspend apareceram no Kotlin 1.3 (2018) junto com as corrotinas como um recurso experimental e tornaram-se estáveis no Kotlin 1.5 (2021). Antes disso, a assincronia em Kotlin/Java era alcançada por meio de callbacks, RxJava e CompletableFuture. As funções suspend ofereceram uma alternativa com sintaxe linear e gerenciamento automático de threads.

Como funcionam as funções suspend: Continuation e máquina de estados

Entender o funcionamento interno das funções suspend é a chave para trabalhar corretamente com corrotinas. Diferentemente das funções comuns, cada função suspend é compilada em uma classe com a interface Continuation.

Continuation — o parâmetro oculto

O compilador Kotlin adiciona um parâmetro do tipo Continuation ao final de cada lista de parâmetros de uma função suspend. Continuation contém:

• context — CoroutineContext (dispatcher, job, elementos do contexto)
• resumeWith — método para retomar a execução com um resultado ou exceção
• label — índice do estado atual na máquina de estados

Exemplo de máquina de estados

Suponha que temos uma função suspend com duas chamadas a outras funções suspend:

suspend fun process() {
    val a = stepOne()
    val b = stepTwo(a)
    println(b)
}

O compilador a transforma em uma máquina de estados com rótulos:

// Simplified generated code representation
fun process(cont: Continuation<Unit>): Any? {
    val cont = cont as ProcessContinuation
    when (cont.label) {
        0 -> {
            cont.label = 1
            if (stepOne(cont) == COROUTINE_SUSPENDED) return COROUTINE_SUSPENDED
        }
        1 -> {
            cont.label = 2
            val a = cont.result as TypeA
            if (stepTwo(a, cont) == COROUTINE_SUSPENDED) return COROUTINE_SUSPENDED
        }
        2 -> {
            println(cont.result)
            Unit
        }
    }
}

Observação chave: se a função retornar COROUTINE_SUSPENDED, a thread atual é liberada. Quando a operação assíncrona é concluída, Continuation.resumeWith é chamado e a máquina de estados continua a partir do próximo rótulo.

Sintaxe de funções suspend: declaração e invocação

Declarar uma função suspend não é diferente de uma função comum, exceto pela palavra-chave suspend antes de fun. Há apenas uma restrição: uma função suspend só pode ser chamada de uma corrotina ou de outra função suspend.

Declaração básica

suspend fun delayAndReturn(ms: Long): String {
    delay(ms)
    return "Done after ${ms}ms"
}

Neste exemplo, delay também é uma função suspend que suspende a corrotina pelo número especificado de milissegundos sem bloquear a thread. Após o atraso, a execução é retomada.

Chamada de uma corrotina

fun main() = runBlocking {
    val result = delayAndReturn(1000)
    println(result)
}

runBlocking cria uma ponte entre o mundo comum e as corrotinas. Dentro da lambda, qualquer função suspend pode ser chamada.

Lambdas suspend e tipos funcionais

Kotlin suporta versões suspend de tipos funcionais — suspend () -> T e suspend (A) -> B. Isso permite passar lambdas assíncronas para funções de ordem superior:

suspend fun  withRetry(
    retries: Int = 3,
    block: suspend () -> T
): T {
    repeat(retries - 1) {
        try { return block() }
        catch (_: Exception) { delay(100) }
    }
    return block()
}

A função withRetry recebe uma lambda suspend e tenta novamente sua execução em caso de erro. Este é um padrão típico para requisições de rede com tentativas.

Diferenças entre funções suspend e funções comuns

As diferenças entre funções suspend e comuns vão além de simplesmente adicionar um modificador. Vejamos as principais distinções.

Por que funções suspend não podem ser chamadas de funções comuns

Uma função comum não tem um Continuation — ela não tem onde salvar o estado nem com o que retomar a execução. Se precisar chamar uma função suspend de uma função comum, use runBlocking (para testes) ou CoroutineScope.launch (para produção com ciência do ciclo de vida).

Exemplos de funções suspend no Android

Vejamos três cenários reais de uso de funções suspend em aplicativos Android com Kotlin.

Exemplo 1: Room DAO com consultas suspend

Room suporta funções suspend diretamente — a consulta é executada em uma thread de fundo automaticamente:

@Dao
interface UserDao {
    @Query("SELECT * FROM users WHERE id = :id")
    suspend fun getUser(id: Int): User?

    @Insert
    suspend fun insertUser(user: User)
}

Room usa internamente Dispatchers.IO para executar a consulta, e o resultado é retornado no dispatcher onde a função suspend foi chamada.

Exemplo 2: Composição de funções suspend para carregamento de tela

class ProfileViewModel : ViewModel() {
    private val repo = ProfileRepository()

    fun loadProfile(id: String) {
        viewModelScope.launch {
            val profile = repo.getProfile(id)
            _profile.value = profile
        }
    }
}

ViewModelScope.launch cria uma corrotina, dentro da qual a função suspend getProfile é chamada. Após obter o resultado, a UI é atualizada na thread principal.

Exemplo 3: Passos assíncronos sequenciais

suspend fun placeOrder(cart: Cart): OrderResult {
    val validated = validateCart(cart)
    val payment = processPayment(validated)
    val receipt = sendReceipt(payment)
    return receipt
}

Três funções suspend são executadas sequencialmente. Em cada passo, a corrotina pode suspender sem bloquear a thread. Se algum passo lançar uma exceção, os passos restantes não são executados, protegendo contra estados de pedido incorretos.

Erros comuns ao trabalhar com funções suspend

Mesmo desenvolvedores Kotlin experientes cometem erros ao projetar funções suspend. Vejamos os mais comuns.

Erro 1: Chamadas bloqueantes dentro de suspend

Uma função suspend não torna o código automaticamente assíncrono. Thread.sleep(), InputStream.read() e outras chamadas bloqueantes ainda bloquearão a thread. Use withContext(Dispatchers.IO) para envolver operações bloqueantes.

Erro 2: Criar funções suspend sem necessidade

Se uma função não chama outras funções suspend e não realiza operações assíncronas — o modificador suspend é redundante. Ele adiciona sobrecarga à máquina de estados e restringe o contexto de chamada. Torne uma função suspend apenas quando ela realmente suspende.

Erro 3: Ignorar CancellationException

Quando uma corrotina é cancelada, funções suspend lançam CancellationException. Não a capture sem pensar — você priva o código chamador da capacidade de completar corretamente o cancelamento. Se precisar realizar uma operação de finalização, use um bloco finally e NonCancellable.

suspend fun safeOperation() {
    try {
        doWork()
    } finally {
        withContext(NonCancellable) {
            cleanup()
        }
    }
}

O bloco finally sempre executa, inclusive no cancelamento, e NonCancellable garante que a limpeza não seja interrompida.

Erro 4: Chamar funções suspend de callbacks

Você não pode chamar uma função suspend diretamente de um callback sem criar uma corrotina. Use suspendCoroutine ou suspendCancellableCoroutine para adaptar o estilo de callback às corrotinas.