CKTIS / JavaScript
Transférer un ArrayBuffer avec postMessage : propriété et détachement
Transférer un `ArrayBuffer` avec `postMessage()` détache le tampon de l’expéditeur avant la réception. Sans liste de transfert, les octets sont copiés.
Version : ECMAScript 2024 and the current web platform; runtime support varies
Syntaxe
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] })Si un ArrayBuffer ordinaire figure dans le message mais pas dans la liste de transfert, le clonage structuré copie ses octets et l’expéditeur peut toujours utiliser son tampon. Inscrire le tampon dans la liste transfère la propriété de la mémoire sous-jacente au lieu de la partager. Si le transfert réussit, le tampon de l’expéditeur est déjà détaché au retour de l’appel. Si le message arrive, le destinataire reçoit dans event.data un nouvel objet tampon contenant les octets d’origine lors d’un événement message ultérieur. Le détachement ne confirme pas la livraison.
Placez le même tampon dans le message, par exemple { buffer }, et dans la liste de transfert [buffer]. Le mettre seulement dans la liste peut le détacher sans le rendre accessible dans les données du message. Une vue Uint8Array ou DataView peut être clonée, mais ne peut pas figurer elle-même dans la liste de transfert. Utilisez view.buffer : le transfert porte sur tout le tampon sous-jacent, pas seulement sur la plage de la vue.
Le détachement ne supprime ni l’objet ni ses références. buffer.byteLength et le byteLength des tableaux typés existants qui utilisent ce tampon renvoient 0, mais lire le byteLength d’une DataView qui l’utilise lève une TypeError. Une longueur de 0 ne prouve pas le détachement : un tampon non détaché peut être vide. Si l’accesseur ArrayBuffer.prototype.detached d’ECMAScript 2024 est disponible, vérifiez buffer.detached.
Un tampon en double ou déjà détaché, une vue ou un SharedArrayBuffer dans la liste, ou une valeur non clonable dans le message, comme une fonction, peuvent déclencher de façon synchrone une DOMException nommée DataCloneError. Quand l’envoi d’un SharedArrayBuffer est autorisé, la mémoire est partagée et non transférée.
Worker, MessagePort et le contexte global d’un worker dédié acceptent après le message une liste ou les options { transfer }. Pour une fenêtre, placez targetOrigin avant la liste ou utilisez { targetOrigin, transfer }. La valeur par défaut "/" désigne l’origine de l’expéditeur. Si l’origine cible est connue, indiquez-la précisément plutôt que d’utiliser "*". À la réception, vérifiez event.origin, event.source si nécessaire et la validité des données. postMessage() est une API de la plateforme Web, pas d’ECMAScript ; sa prise en charge dépend de l’environnement d’exécution.
Exemples
(() => {
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}`);
})();Résultat
before: buffer=3, view=3 after: buffer=0, view=0 received: 3 bytes (7, 42, 255)
Exécutez le code dans la console de développement d’un navigateur. Les deux ports fonctionnent sur la même page, sans worker. Les deux lignes de l’expéditeur doivent précéder celle du destinataire, qui affiche les trois octets inchangés.
Leçons associées
- JavaScript · Leçon 5 · Avancé · Version : 4
Sources
- 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