Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

Trasferire un ArrayBuffer con postMessage: proprietà e distacco

Trasferire un `ArrayBuffer` con `postMessage()` scollega il buffer del mittente prima della consegna. Senza elenco di trasferimento, i byte vengono copiati.

Versione: ECMAScript 2024 and the current web platform; runtime support varies

Sintassi

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 un normale ArrayBuffer è nel messaggio ma non nell’elenco di trasferimento, la clonazione strutturata ne copia i byte e il mittente può continuare a usare il proprio buffer. Includerlo nell’elenco trasferisce la proprietà della memoria sottostante invece di condividerla. Se il trasferimento riesce, il buffer del mittente è già scollegato quando la chiamata termina. Se il messaggio arriva, il destinatario riceve in event.data un nuovo oggetto buffer con i byte originali in un successivo evento message. Il distacco non conferma la consegna.

Inserisci lo stesso buffer nel messaggio, ad esempio { buffer }, e nell’elenco di trasferimento [buffer]. Inserirlo solo nell’elenco può scollegarlo senza renderlo accessibile nei dati del messaggio. Un Uint8Array o un DataView può essere clonato, ma non può comparire direttamente nell’elenco di trasferimento. Usa view.buffer: viene trasferito tutto il buffer sottostante, non solo l’intervallo della vista.

Il distacco non elimina l’oggetto né i riferimenti a esso. buffer.byteLength e la proprietà byteLength degli array tipizzati esistenti che usano quel buffer restituiscono 0; leggere byteLength su un DataView che lo usa genera invece TypeError. Una lunghezza di 0 non basta a dimostrare il distacco: anche un buffer non scollegato può essere vuoto. Se il getter ArrayBuffer.prototype.detached di ECMAScript 2024 è disponibile, controlla buffer.detached.

Un buffer duplicato o già scollegato, una vista o uno SharedArrayBuffer nell’elenco, oppure un valore non clonabile nel messaggio, come una funzione, possono generare in modo sincrono una DOMException di nome DataCloneError. Se l’invio di uno SharedArrayBuffer è consentito, la memoria viene condivisa anziché trasferita.

Worker, MessagePort e il contesto globale di un worker dedicato accettano dopo il messaggio un elenco oppure le opzioni { transfer }. Per una finestra, passa targetOrigin prima dell’elenco o usa { targetOrigin, transfer }. Il valore predefinito "/" indica l’origine del mittente. Se conosci l’origine di destinazione, specificala esattamente invece di usare "*". Alla ricezione, controlla event.origin, event.source quando pertinente e la validità dei dati. postMessage() è un’API della piattaforma web, non di ECMAScript; il supporto dipende dall’ambiente di esecuzione.

Esempi

(() => {
  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}`);
})();

Risultato

before: buffer=3, view=3
after: buffer=0, view=0
received: 3 bytes (7, 42, 255)

Esegui il codice nella console per sviluppatori del browser. Le due porte funzionano nella stessa pagina, senza worker. Sono previste prima le due righe del mittente e poi quella del destinatario con i tre byte invariati.

Lezioni correlate

  • JavaScript · Lezione 5 · Avanzato · Versione: 4

Fonti