Skip to content

cancel ​

cancel pede a uma Promise pendente que pare. O trabalho desenrola pela limpeza dele e a Promise settla como cancelada.

Assinaturacancel<T>(promise: Promise<T>, reason: string, graceMillis?: u64): boolean

Devolve true apenas para a chamada que inicia o cancelamento, e false para uma que chega depois de a Promise já ter settlado ou já ter sido mandada parar.

O cancelamento é cooperativo: ele tem efeito num ponto de suspensão, nunca no meio de um statement. Uma tarefa no meio de uma computação longa não alcança ponto de suspensão nenhum e por isso não é interrompida; isCancelled é o que um laço desses usa para parar sozinho.

O que roda, e o que não ​

Uma tarefa cancelada roda os blocos finally dela e então sai. Tudo o que ela segura atravessando um await é liberado, e os statements depois do bloco não rodam.

Um catch não enxerga o cancelamento. Um catch é escrito para as falhas que o programa espera do próprio trabalho, e tratar "você foi mandado parar" como uma delas significa que um handler que registra e segue, ou que tenta de novo, começa trabalho novo numa tarefa que já está terminando.

Ser cancelado e esperar por algo cancelado são coisas diferentes, e só a primeira pula o catch. Uma tarefa que espera por uma Promise que outra pessoa cancelou não foi mandada parar, e o catch dela é o único lugar onde ela pode saber o que aconteceu.

tyrus
import { cancel, sleepAsync } from "tyrus:task";

const transfer = async (): Promise<void> => {
    try {
        await sleepAsync(1_000);
    } catch (error: Error) {
        // A cancellation never arrives here.
        print("failed");
    } finally {
        print("released");
        print("assert:", "released");
    }
};

const main = async (): Promise<void> => {
    const running: Promise<void> = transfer();
    await sleepAsync(50);
    const asked: boolean = cancel(running, "Cancelled by caller");
    print(asked);
    print("assert:", true);

    try {
        // Returns once `transfer` has finished releasing what it held.
        await running;
    } catch (error: Error) {
        print(error.message);
        print("assert:", "Cancelled by caller");
    }
};

Quando a Promise settla ​

Quando o trabalho termina de desenrolar, não quando o pedido é feito. Um chamador que para um worker e em seguida reusa a porta, o arquivo ou a conexão dele estaria correndo contra a liberação, o que aparece como uma falha rara em vez de uma resposta errada.

O motivo que o chamador passou é o que a Promise carrega, seja lá o que a tarefa alcançou na saída: um valor que ela conseguiu retornar é produto de trabalho que já tinha sido mandado parar.

O cancelamento alcança o trabalho que o runtime faz em nome da tarefa. Uma tarefa esperando por uma requisição tem essa requisição interrompida, e a conexão fecha.

O prazo ​

graceMillis limita quanto tempo a limpeza pode levar. Passado ele, o trabalho é cortado, e a Promise carrega cancellation cleanup exceeded its deadline em vez do motivo original, porque de outro modo o chamador não teria como distinguir uma parada limpa de uma que abandonou o trabalho pela metade.

Omiti-lo significa que a limpeza nunca é cortada. Limpeza que ainda está progredindo não é algo para interromper por suposição, então quem tem pressa é quem diz quanto vai esperar.