CKTIS / JavaScript
Transferir um ArrayBuffer com postMessage: propriedade e desassociação
Transferir um `ArrayBuffer` com `postMessage()` desassocia o buffer do emissor antes da entrega. Sem lista de transferência, os bytes são copiados.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
worker.postMessage(message)
worker.postMessage(message, [buffer])
worker.postMessage(message, { transfer: [buffer] })
self.postMessage(message, [buffer]) // Dedicated worker global scope
port.postMessage(message, [buffer])
port.postMessage(message, { transfer: [buffer] })
targetWindow.postMessage(message, targetOrigin, [buffer])
targetWindow.postMessage(message, { targetOrigin, transfer: [buffer] })Se um ArrayBuffer normal constar da mensagem, mas não da lista de transferência, a clonagem estruturada copia os bytes e o emissor pode continuar a usar o seu buffer. Incluir o buffer na lista transfere a propriedade da memória subjacente em vez de a partilhar. Se a transferência for bem-sucedida, o buffer do emissor já está desassociado quando a chamada termina. Se a mensagem chegar, o destinatário obtém em event.data um novo objeto buffer com os bytes originais num evento message posterior. A desassociação não confirma a entrega.
Coloca o mesmo buffer na mensagem, por exemplo { buffer }, e na lista de transferência [buffer]. Colocá-lo apenas na lista pode desassociá-lo sem o disponibilizar nos dados da mensagem. Um Uint8Array ou um DataView pode ser clonado, mas não pode constar diretamente da lista de transferência. Usa view.buffer: é transferido todo o buffer subjacente, não apenas o intervalo da vista.
A desassociação não elimina o objeto nem as referências a este. buffer.byteLength e o byteLength dos arrays tipados existentes que usam esse buffer devolvem 0, mas ler byteLength num DataView que o usa lança TypeError. O valor 0 não prova a desassociação: um buffer não desassociado pode estar vazio. Se o getter ArrayBuffer.prototype.detached do ECMAScript 2024 estiver disponível, verifica buffer.detached.
Um buffer repetido ou já desassociado, uma vista ou um SharedArrayBuffer na lista, ou um valor não clonável na mensagem, como uma função, podem provocar de forma síncrona uma DOMException com o nome DataCloneError. Quando é permitido enviar um SharedArrayBuffer, a memória é partilhada em vez de se transferir a sua propriedade.
Worker, MessagePort e o contexto global de um worker dedicado aceitam, depois da mensagem, uma lista ou as opções { transfer }. Para uma janela, indica targetOrigin antes da lista ou usa { targetOrigin, transfer }. O valor predefinido "/" designa a origem do emissor. Se conheceres a origem de destino, indica-a exatamente, em vez de usares "*". Na receção, confirma event.origin, verifica event.source quando pertinente e valida os dados. postMessage() é uma API da plataforma Web, não do ECMAScript; o suporte depende do ambiente de execução.
Exemplos
(() => {
const { port1, port2 } = new MessageChannel();
const view = new Uint8Array([7, 42, 255]);
const buffer = view.buffer;
port2.onmessage = ({ data }) => {
const bytes = new Uint8Array(data.buffer);
console.log(`received: ${bytes.byteLength} bytes (${bytes.join(', ')})`);
port1.close();
port2.close();
};
console.log(`before: buffer=${buffer.byteLength}, view=${view.byteLength}`);
port1.postMessage({ buffer }, [buffer]);
console.log(`after: buffer=${buffer.byteLength}, view=${view.byteLength}`);
})();Resultado
before: buffer=3, view=3 after: buffer=0, view=0 received: 3 bytes (7, 42, 255)
Executa o código na consola de desenvolvimento de um navegador. As duas portas funcionam na mesma página, sem um worker. São esperadas primeiro as duas linhas do emissor e depois a do destinatário, com os três bytes inalterados.
Lições relacionadas
- JavaScript · Lição 5 · Avançado · Versão: 4
Fontes
- HTML Standard — Safe passing of structured data
- HTML Standard — StructuredSerializeWithTransfer (value, transferList)
- HTML Standard — Cross-document messaging
- HTML Standard — Channel messaging
- HTML Standard — Dedicated workers and the Worker interface
- ECMAScript 2024 Language Specification — Properties of the ArrayBuffer Prototype Object
- ECMAScript 2024 Language Specification — get DataView.prototype.byteLength
- ECMAScript 2024 Language Specification — Properties of the %TypedArray% Prototype Object