KennisbankExamencentrum
NL · NLNederlands (Nederland)
Taal kiezen13

CKTIS / JavaScript

WritableStream-sink: start, write, close en abort

Vier optionele sinkmethoden bepalen hoe een schrijfbare stream zijn bestemming voorbereidt, gegevensblokken schrijft, normaal afsluit of na afbreken opruimt.

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

Syntax

new WritableStream()
new WritableStream(underlyingSink)
new WritableStream(underlyingSink, queuingStrategy)

// Optional methods on underlyingSink:
const underlyingSink = {
  start(controller) { /* initialize the destination */ },
  write(chunk, controller) { /* write one chunk */ },
  close() { /* finalize successful output */ },
  abort(reason) { /* clean up after an abort request */ },
};

WritableStream hoort bij de Web Streams API, niet bij ECMAScript 2024; de beschikbaarheid hangt af van de runtime. underlyingSink, het eerste optionele constructorargument, is een object waarvan de stream de methoden aanroept. Het tweede optionele argument, queuingStrategy, bepaalt hoe de wachtrijgrootte voor tegendruk (backpressure) wordt gemeten.

start(controller) wordt tijdens de constructie één keer aangeroepen. Een synchroon opgegooide uitzondering laat de constructie mislukken; een afgewezen promise zet de aangemaakte stream in een fouttoestand. De stream wacht tot de initialisatie slaagt voordat hij blokken aan de sink doorgeeft. write(chunk, controller) verwerkt één blok tegelijk, in de volgorde waarin de blokken zijn aangeboden. Geef een promise terug voor het daadwerkelijke asynchrone schrijven, zodat de stream erop kan wachten en fouten kan doorgeven.

close() krijgt geen argumenten. Na een verzoek tot sluiten wordt deze methode pas aangeroepen als alle geaccepteerde schrijfbewerkingen zijn geslaagd. Gebruik haar om buffers van de sink weg te schrijven en middelen vrij te geven. abort(reason) ruimt op na een verzoek tot afbreken; de reden kan elke JavaScript-waarde zijn. Nog niet gestarte schrijfbewerkingen worden afgewezen, maar een lopende bewerking stopt niet automatisch en voltooid schrijfwerk wordt niet ongedaan gemaakt. Beide methoden kunnen een promise teruggeven; ga er niet van uit dat abort bij elke fout of na het sluiten wordt aangeroepen.

start en write ontvangen dezelfde WritableStreamDefaultController. Met controller.signal kan een lopende bewerking op een afbreekverzoek reageren als die bewerking annulering ondersteunt. controller.error(error) meldt een streamfout; het is geen afbreekverzoek en vervangt het opruimen niet.

De producent roept getWriter() aan, dat de stream exclusief aan één writer koppelt. Handel de promises van writer.write(), writer.close() en writer.abort() af; directe aanroepen van stream.close() en stream.abort() leveren een afgewezen promise op zolang de stream vergrendeld is. writer.releaseLock() heft de vergrendeling op zonder de stream te beëindigen.

Voorbeelden

(async () => {
  const log = [];
  const reason = new Error("stop");

  async function run(label, shouldAbort) {
    const stream = new WritableStream({
      start() {
        log.push(`${label}: start`);
      },
      async write(chunk) {
        await Promise.resolve();
        log.push(`${label}: write ${chunk}`);
      },
      close() {
        log.push(`${label}: close`);
      },
      abort(received) {
        log.push(`${label}: abort (${received === reason})`);
      },
    });

    const writer = stream.getWriter();
    try {
      await writer.write("A");
      if (shouldAbort) {
        await writer.abort(reason);
      } else {
        await writer.close();
      }
    } finally {
      writer.releaseLock();
    }
  }

  await run("normal", false);
  await run("interrupted", true);
  console.log(log.join("\n"));
})().catch(console.error);

Resultaat

normal: start
normal: write A
normal: close
interrupted: start
interrupted: write A
interrupted: abort (true)

Het voorbeeld gebruikt twee afzonderlijke streams. Beide schrijven `A` volledig; de eerste wordt gesloten en de tweede afgebroken. `true` laat zien dat de sink precies hetzelfde `Error`-object heeft ontvangen.

Gerelateerde lessen

  • JavaScript · Les 4 · Gevorderd · Versie: 4

Bronnen