From aacefe16a99ef813a78e7769ec72ace150334602 Mon Sep 17 00:00:00 2001 From: Adam Rice Date: Wed, 29 Mar 2017 18:38:08 +0900 Subject: [PATCH 1/4] Early draft of WritableStream "Design Philosophy" section This is supposed to help implementors and others understand the design principles. Markup isn't done properly yet, so please evaluate the text only. --- index.bs | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/index.bs b/index.bs index c670f1c40..921f9a31b 100644 --- a/index.bs +++ b/index.bs @@ -2568,6 +2568,43 @@ nothrow>ReadableByteStreamControllerShouldCallPull ( controller ) console.error("Something broke", e)); + +

Design Philosophy

+ +
While sharing the principles for streams in general, a number of additional principles have informed the design of +the WritableStream class.
+ + +

Class WritableStream

Class Definition

From 09574428593f0b0837d702639928938fd3a4a972 Mon Sep 17 00:00:00 2001 From: Adam Rice Date: Wed, 29 Mar 2017 18:48:16 +0900 Subject: [PATCH 2/4] Add note about consistent order of promise resolution Also about developer predictability > implementation simplicity. --- index.bs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/index.bs b/index.bs index 921f9a31b..19a42f325 100644 --- a/index.bs +++ b/index.bs @@ -2603,8 +2603,13 @@ the WritableStream class. have confidence that all other operations have ceased.
  • This principle also applies to the ReadableStream pipeTo() method. +

  • Promises resolve or reject in consistent order. In particular, writer.ready always resolves before + writer.closed, even in cases where they both resolve "at the same time". +

    Some of these design decisions improve predictability, ease-of-use and safety for developers at the expense of +making implementations more complex.
    +

    Class WritableStream

    Class Definition

    From 333f6ae51b5fac5caf79b1a562a19bd7ce60fec1 Mon Sep 17 00:00:00 2001 From: Adam Rice Date: Thu, 30 Mar 2017 14:37:02 +0900 Subject: [PATCH 3/4] Changes to the text --- index.bs | 41 +++++++++++++++++++---------------------- 1 file changed, 19 insertions(+), 22 deletions(-) diff --git a/index.bs b/index.bs index 19a42f325..7cad21b95 100644 --- a/index.bs +++ b/index.bs @@ -2569,47 +2569,44 @@ nothrow>ReadableByteStreamControllerShouldCallPull ( controller ) -

    Design Philosophy

    +

    Design Of The State Machine

    -
    While sharing the principles for streams in general, a number of additional principles have informed the design of -the WritableStream class.
    +

    In addition to the principles for streams in general, a number of additional considerations have informed the design of +the WritableStream state machine. + +

    Some of these design decisions improve predictability, ease-of-use, and safety for developers at the expense of +making implementations more complex.

    • Only one sink method can ever be executing at a time. -

    • Sink methods are treated as atomic. -

        -

      • "Atomic" here means that the time between a sink method being called and the returned Promise resolving or - rejecting is treated as indivisible. -

      • A new sink method will never be called until the Promise from the previous one has resolved. -

      • State changes do not take effect until any in-flight sink method has completed. -

      +

    • Sink methods are treated as atomic. A new sink method will never be called until the Promise from the previous + one has resolved. Most changes to the internal state do not take effect until any in-flight sink method has completed.

    • Exception: If something has happened that will error the stream, for example writer.abort() has been called, then new calls to writer.write() will start failing immediately. There's no user benefit in waiting for the current operation to complete before informing the user that writer.write() has failed.

    • The writer.ready promise and the value of writer.desiredSize reflect whether a write() performed right now would be effective.

        -
      • writer.ready and writer.desiredSize will change even in the middle of executing a sink method, as soon as we - know that calling writer.write() won't work any more. +
      • They will change even while a sink method is in-flight. writer.ready will reject as soon as new + calls to writer.write() will start failing. writer.desiredSize will change to null at the same time.
        Because promises are dispatched asynchronously, the state can still change between - writer.ready becoming fulfilled and write() being called.
        + writer.ready becoming fulfilled and write() being called.
      • The value of writer.desiredSize decreases synchronously with every call to writer.write(). This implies that - strategy.size() is executed synchronously. -
      + the queueing strategy's size() function is executed synchronously. +

  • The writer.closed promise and the promises returned by writer.close() and writer.abort() do not resolve or - reject until no sink methods are executing and no further sink methods will be executing. + reject until no sink methods are executing and no further sink methods will be executed.

      -
    • If the user of the WritableStream wants to retry against the same underlying data item, it is important to +
    • If the user of the WritableStream wants to retry using the same underlying file, etc., it is important to have confidence that all other operations have ceased.
    • This principle also applies to the ReadableStream pipeTo() method.
    -

  • Promises resolve or reject in consistent order. In particular, writer.ready always resolves before - writer.closed, even in cases where they both resolve "at the same time". +

  • Promises fulfill in consistent order. In particular, writer.ready always resolves before writer.closed, even + in cases where both are fulfilling in reaction to the same occurrence. +

  • Queued calls to writer methods such as write() are not cancelled when writer.releaseLock() is called. This makes + them easy to use in a "fire and forget" style. -
    Some of these design decisions improve predictability, ease-of-use and safety for developers at the expense of -making implementations more complex.
    -

    Class WritableStream

    Class Definition

    From c32b030f74172caf2f521bd8b312acc139aaccf8 Mon Sep 17 00:00:00 2001 From: Adam Rice Date: Thu, 30 Mar 2017 14:38:19 +0900 Subject: [PATCH 4/4] Change the id of the title to match --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 7cad21b95..4b71b1265 100644 --- a/index.bs +++ b/index.bs @@ -2569,7 +2569,7 @@ nothrow>ReadableByteStreamControllerShouldCallPull ( controller ) -

    Design Of The State Machine

    +

    Design Of The State Machine

    In addition to the principles for streams in general, a number of additional considerations have informed the design of the WritableStream state machine.