Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Worker: tratar `message`, `error` e `messageerror`

Distingue três eventos de um worker dedicado: uma mensagem recebida, um erro do worker e uma mensagem que o destinatário não consegue desserializar.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

const worker = new Worker(url);
worker.onmessage = (event) => { /* use event.data */ };
worker.onerror = (event) => { /* handle a worker error */ };
worker.onmessageerror = (event) => { /* handle a receive-side deserialization failure */ };

// Alternative for any of the three properties:
worker.addEventListener("message", handleMessage);
worker.addEventListener("error", handleError);
worker.addEventListener("messageerror", handleMessageError);

worker.onmessage, worker.onerror e worker.onmessageerror são propriedades de tratamento de eventos da instância de Worker dedicado, do lado que a criou. São definidas pelo padrão HTML, não pelo ECMAScript 2024. O suporte depende do ambiente de execução, sobretudo para messageerror. Configura os gestores de eventos antes de enviares o primeiro pedido.

onmessage recebe um MessageEvent quando uma mensagem do worker é desserializada com sucesso. Lê o conteúdo em event.data e confirma que tem a estrutura esperada pela aplicação: a clonagem estruturada não valida o teu protocolo. Dentro do worker, self.onmessage trata o sentido inverso, ou seja, as mensagens do contexto que o criou.

onerror recebe um único objeto de evento. Uma exceção síncrona não capturada que seja comunicada ao contexto criador origina um ErrorEvent; não contes com event.error para obter a exceção original. Uma falha no carregamento do script pode originar um simples Event. Se o evento for cancelável, event.preventDefault() pode impedir que o erro continue a ser comunicado, mas não retoma o código interrompido. Dentro do worker, self.onerror tem uma forma histórica com cinco argumentos para ErrorEvent e pode cancelar a comunicação com return true; esta regra não se aplica a worker.onerror.

onmessageerror recebe um MessageEvent não cancelável em vez de message quando o destinatário não consegue desserializar uma mensagem. Não há conteúdo descodificado para ler. Em contrapartida, passar uma função a postMessage() lança DataCloneError de forma síncrona do lado do remetente e não gera messageerror do lado do destinatário.

Cada propriedade guarda um único gestor: uma nova atribuição substitui-o e a atribuição de null remove-o. Usa addEventListener() com o nome do evento sem on para registar ouvintes independentes. Chama worker.terminate() quando já não precisares do worker; o método não espera que o trabalho pendente termine.

Exemplos

(() => {
  const inNode = typeof require === "function" &&
    typeof process !== "undefined" && Boolean(process.versions?.node);

  const handler = `
    function handleMessage(data, reply) {
      if (data === "fail") throw new Error("demo failure");
      reply(data * 2);
    }
  `;

  let worker;
  let messageErrorTarget;

  function reportMessageError(event) {
    console.log(event.isTrusted ? "messageerror" : "messageerror (synthetic)");
  }

  function receiveReply(data) {
    console.log(`message: ${data}`);
    messageErrorTarget.dispatchEvent(new MessageEvent("messageerror"));
    worker.postMessage("fail");
  }

  if (inNode) {
    const { Worker: ThreadWorker } = require("node:worker_threads");
    worker = new ThreadWorker(handler + `
      const { parentPort } = require("node:worker_threads");
      parentPort.on("message", (data) => {
        handleMessage(data, (value) => parentPort.postMessage(value));
      });
    `, { eval: true });

    // Node worker threads do not use the browser's handler properties.
    messageErrorTarget = new EventTarget();
    messageErrorTarget.addEventListener("messageerror", reportMessageError);
    worker.on("message", receiveReply);
    worker.on("error", (error) => {
      if (error.message !== "demo failure") throw error;
      console.log("error: runtime");
    });
  } else {
    const script = handler + `
      self.onmessage = ({ data }) => {
        handleMessage(data, (value) => self.postMessage(value));
      };
    `;
    const url = URL.createObjectURL(new Blob([script], { type: "text/javascript" }));
    try {
      worker = new Worker(url);
    } catch (error) {
      URL.revokeObjectURL(url);
      throw error;
    }

    messageErrorTarget = worker;
    worker.onmessage = (event) => receiveReply(event.data);
    worker.onmessageerror = reportMessageError;
    worker.onerror = (event) => {
      event.preventDefault();
      console.log(event instanceof ErrorEvent ? "error: runtime" : "error: startup");
      worker.terminate();
      URL.revokeObjectURL(url);
    };
  }

  try {
    worker.postMessage(() => {});
  } catch (error) {
    console.log(`send: ${error.name}`);
  }
  worker.postMessage(21);
})();

Resultado

send: DataCloneError
message: 42
messageerror (synthetic)
error: runtime

Para experimentares as propriedades de tratamento de eventos de Web Workers, executa o exemplo completo na consola do navegador, numa página cuja política de segurança permita workers `blob:`. Em Node.js 24, guarda o código em `main.cjs` e executa `node main.cjs`; este ramo usa `node:worker_threads`, não as propriedades de tratamento de eventos do `Worker` do navegador. Nos dois ambientes, `messageerror (synthetic)` testa apenas o gestor, não uma falha real de desserialização nem o suporte nativo do evento.

Lições relacionadas

  • JavaScript · Lição 32 · Avançado · Versão: 4

Fontes