WritableStreamDefaultWriter.releaseLock() — Methode · JavaScript-Referenz

Signatur

WritableStreamDefaultWriter.prototype.releaseLock()

Beschreibung

Wenn Sie stream.getWriter() aufrufen, wird der WritableStream für genau diesen Writer gesperrt. Solange die Sperre besteht, kann kein anderer Writer erzeugt werden, und auch ReadableStream.prototype.pipeTo() oder pipeThrough() können nicht in diesen Stream schreiben. Mit releaseLock() geben Sie die Sperre wieder frei. stream.locked ist danach false.

Die Methode wird typischerweise genutzt, wenn ein Codeabschnitt nur vorübergehend in einen Stream schreiben soll, etwa eine Kopfzeile oder einen Präfix, und der Stream danach an anderen Code oder an eine Pipe weitergegeben wird. Bewährt hat sich das Muster try { … } finally { writer.releaseLock(); }. Damit wird die Sperre auch im Fehlerfall zuverlässig freigegeben.

Nach der Freigabe ist der Writer nicht mehr verwendbar: write(), close() und abort() liefern abgelehnte Promises mit einem TypeError, und der Zugriff auf desiredSize wirft einen TypeError. Die Promises writer.closed und writer.ready werden ebenfalls mit einem TypeError abgelehnt, sofern sie noch nicht erfüllt waren. Der Stream selbst bleibt dabei unverändert. Er wird weder geschlossen noch abgebrochen.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück.

Beispiele

Sperre freigeben und neuen Writer holen

const chunks = [];
const stream = new WritableStream({
  write(chunk) { chunks.push(chunk); }
});

const writer1 = stream.getWriter();
await writer1.write('Kopfzeile\n');
writer1.releaseLock();
console.log(stream.locked);

// Jetzt kann ein anderer Writer übernehmen
const writer2 = stream.getWriter();
await writer2.write('Inhalt\n');
await writer2.close();
console.log(chunks);

false [ 'Kopfzeile\n', 'Inhalt\n' ]

Sicheres Muster mit try/finally vor pipeTo()

const encoder = new TextEncoder();
const sink = new WritableStream({
  write(chunk) { console.log('Empfangen:', new TextDecoder().decode(chunk)); }
});

const writePrefix = async (stream) => {
  const writer = stream.getWriter();
  try {
    await writer.write(encoder.encode('--- Anfang ---'));
  } finally {
    // Sperre immer freigeben, auch bei Fehlern
    writer.releaseLock();
  }
};

await writePrefix(sink);

// pipeTo() funktioniert nur, weil der Stream nicht mehr gesperrt ist
const source = new ReadableStream({
  start(controller) {
    controller.enqueue(encoder.encode('Daten'));
    controller.close();
  }
});
await source.pipeTo(sink);

Empfangen: --- Anfang --- Empfangen: Daten

Verhalten eines freigegebenen Writers

const stream = new WritableStream();
const writer = stream.getWriter();

writer.closed.catch((err) => console.log('closed:', err.name));
writer.releaseLock();

try {
  await writer.write('zu spät');
} catch (err) {
  console.log('write:', err.name);
}

// Mehrfaches Freigeben ist unkritisch
writer.releaseLock();
console.log('locked:', stream.locked);

closed: TypeError write: TypeError locked: false

// Wichtig · Fallstricke

Keine Verbindung zu close(): releaseLock() schließt den Stream nicht. Wenn Sie den Stream beenden möchten, rufen Sie vorher await writer.close() auf.
Ausstehende Schreibvorgänge: Ältere Spezifikationsstände und Implementierungen warfen einen TypeError, wenn noch Schreibvorgänge liefen. Heute ist die Freigabe jederzeit erlaubt, und bereits eingereihte Chunks werden weiter verarbeitet. Aus Gründen der Kompatibilität sollten Sie trotzdem vorher await writer.write(...) bzw. await writer.ready abwarten.
Unbehandelte Ablehnungen: Nach der Freigabe wird writer.closed abgelehnt. Wenn Sie auf dieses Promise reagiert haben, müssen Sie den TypeError abfangen, sonst droht eine „unhandled rejection“.
Wenn Sie releaseLock() auf einem bereits freigegebenen Writer aufrufen, passiert nichts (No-op).
Kompatibilität: Chromium ab Version 59, Safari ab 14.1, Firefox ab 100. In Node.js ist die Methode seit Version 16.5 über stream/web verfügbar und ab Version 18 global.

Siehe auch

WritableStreamDefaultWriter WritableStream.getWriter() WritableStream.locked WritableStreamDefaultWriter.close() WritableStreamDefaultWriter.closed ReadableStreamDefaultReader.releaseLock() ReadableStream.pipeTo()