ArrayBuffer.prototype.detached — Eigenschaft · JavaScript-Referenz

Signatur

get ArrayBuffer.prototype.detached

Beschreibung

Die Zugriffseigenschaft detached liefert true, wenn der Speicher eines ArrayBuffer abgetrennt wurde. Das passiert, wenn der Puffer mit ArrayBuffer.prototype.transfer() oder transferToFixedLength() in einen neuen Puffer übertragen wurde. Es passiert auch, wenn er als Transferable an postMessage() oder structuredClone() übergeben wurde. Solange der Puffer nutzbar ist, ist der Wert false.

Ein abgetrennter Puffer hat die byteLength 0. Fast jeder Zugriff darauf löst einen TypeError aus, zum Beispiel slice(), resize(), ein erneutes transfer() oder das Anlegen einer neuen Typed-Array-Sicht. Bestehende Sichten wie Uint8Array haben danach die Länge 0 und geben beim Lesen undefined zurück.

Vor ES2024 musste man einen abgetrennten Puffer indirekt erkennen, meist über byteLength === 0. Das ist unzuverlässig, weil auch ein neuer, leerer Puffer die Länge 0 hat. Mit detached prüfen Sie den Zustand eindeutig, etwa bevor Sie einen Puffer wiederverwenden oder nachdem Sie Daten an einen Worker übertragen haben.

Die Eigenschaft ist schreibgeschützt. Sie hat nur einen Getter und keinen Setter.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Puffer abgetrennt (übertragen) wurde, sonst false.

Beispiele

Zustand vor und nach transfer()

const buffer = new ArrayBuffer(8);
console.log(buffer.detached); // false

const neu = buffer.transfer();
console.log(buffer.detached);   // true
console.log(buffer.byteLength); // 0
console.log(neu.detached);      // false
console.log(neu.byteLength);    // 8

false true 0 false 8

Puffer an einen Web Worker übertragen

const worker = new Worker('worker.js');
const pixel = new Uint8Array(1024 * 1024).buffer;

// Übertragung statt Kopie: der Speicher wandert in den Worker
worker.postMessage(pixel, [pixel]);

console.log(pixel.detached); // true – im Hauptthread nicht mehr nutzbar

true

Schutzprüfung vor der Wiederverwendung

const leseBytes = (buffer) => {
  if (buffer.detached) {
    throw new Error('Puffer wurde bereits übertragen');
  }
  return new Uint8Array(buffer);
};

const buf = new ArrayBuffer(4);
console.log(leseBytes(buf).length); // 4

structuredClone(buf, { transfer: [buf] });
try {
  leseBytes(buf);
} catch (e) {
  console.log(e.message);
}

4 Puffer wurde bereits übertragen

// Wichtig · Fallstricke

Kompatibilität: Die Eigenschaft gibt es erst seit ES2024 (Chrome/Edge 114, Firefox 122, Safari 17.4, Node.js 21). In älteren Umgebungen ist sie undefined. Deshalb funktioniert if (buf.detached) dort still nicht. Prüfen Sie die Unterstützung vorher mit 'detached' in ArrayBuffer.prototype.
byteLength === 0 ist kein zuverlässiger Ersatz, weil auch new ArrayBuffer(0) diese Länge hat.
SharedArrayBuffer hat keine detached-Eigenschaft, weil er nicht übertragen und abgetrennt werden kann.
Nach dem Abtrennen lösen slice(), resize(), transfer() und new Uint8Array(buffer) einen TypeError aus. Bestehende Sichten melden die Länge 0.
Der Getter wirft einen TypeError, wenn er mit einem anderen this als einem ArrayBuffer aufgerufen wird.

Siehe auch

ArrayBuffer[Symbol.species] ArrayBuffer.prototype.resizable ArrayBuffer.prototype.byteLength ArrayBuffer.prototype.maxByteLength Error.prototype.stack