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
- WritableStream: WritableStream() constructor
- WritableStreamDefaultWriter
- WritableStreamDefaultWriter: close() method
- WritableStream: close() method
- WritableStream: abort() method
- WritableStreamDefaultController: signal property
- WritableStreamDefaultController: error() method
- WHATWG Streams Standard — The underlying sink API