Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / JavaScript

Odbiornik WritableStream: start, write, close i abort

Cztery opcjonalne metody odbiornika określają, jak strumień inicjalizuje miejsce docelowe, zapisuje porcje danych, kończy zapis lub sprząta po przerwaniu.

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

Składnia

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 należy do Web Streams API, a nie do ECMAScript 2024; dostępność zależy od środowiska uruchomieniowego. Pierwszy opcjonalny argument konstruktora, underlyingSink, to obiekt z metodami wywoływanymi przez strumień. Drugi opcjonalny argument, queuingStrategy, określa sposób mierzenia kolejki na potrzeby sygnalizowania przeciążenia (backpressure).

start(controller) jest wywoływana raz, podczas konstrukcji. Synchroniczny wyjątek przerywa konstrukcję; odrzucona obietnica wprowadza utworzony strumień w stan błędu. Strumień czeka na udaną inicjalizację, zanim przekaże dane do odbiornika. write(chunk, controller) obsługuje jedną porcję naraz, w kolejności zgłoszeń. Zwróć obietnicę reprezentującą rzeczywisty zapis asynchroniczny, aby strumień mógł na niego zaczekać i przekazać błąd.

close() nie otrzymuje argumentów. Po żądaniu zamknięcia jest wywoływana dopiero wtedy, gdy wszystkie przyjęte zapisy zakończą się pomyślnie. Można w niej opróżnić bufory odbiornika i zwolnić zasoby. abort(reason) służy do sprzątania po żądaniu przerwania; powodem może być dowolna wartość JavaScript. Zapisy, które jeszcze się nie rozpoczęły, są odrzucane, ale trwająca operacja nie jest automatycznie zatrzymywana, a ukończone zapisy nie są cofane. Obie metody mogą zwrócić obietnicę; nie zakładaj, że abort zostanie wywołana przy każdym błędzie lub po zamknięciu.

start i write otrzymują ten sam WritableStreamDefaultController. controller.signal pozwala trwającej operacji zareagować na żądanie przerwania, jeśli operacja obsługuje anulowanie. controller.error(error) sygnalizuje błąd strumienia; nie jest żądaniem przerwania i nie zastępuje sprzątania.

Kod produkujący dane używa getWriter(), który blokuje strumień na rzecz jednego writera. Obsługuj obietnice zwracane przez writer.write(), writer.close() i writer.abort(); bezpośrednie stream.close() i stream.abort() są odrzucane, gdy strumień jest zablokowany. writer.releaseLock() zwalnia blokadę, ale nie kończy strumienia.

Przykłady

(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);

Wynik

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

Przykład używa dwóch osobnych strumieni. Oba kończą zapis `A`; pierwszy się zamyka, drugi zostaje przerwany. `true` oznacza, że odbiornik otrzymał dokładnie ten sam obiekt `Error`.

Powiązane lekcje

  • JavaScript · Lekcja 4 · Zaawansowany · Wersja: 4

Źródła