[Fetch API] Introduce BytesConsumer

third_party/WebKit/Source/modules/fetch/BytesConsumer.h

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef BytesConsumer_h
+#define BytesConsumer_h
+
+#include "modules/ModulesExport.h"
+#include "platform/blob/BlobData.h"
+#include "platform/heap/Handle.h"
+#include "platform/network/EncodedFormData.h"
+#include "wtf/PassRefPtr.h"
+#include "wtf/text/WTFString.h"
+
+namespace blink {
+
+// BytesConsumer represents the "consumer" side of a data pipe. A user
+// can read data from it.
+//
+// A BytesConsumer is bound to the thread on which it is created.
+// BytesConsumer has four states: waiting, readable, closed and errored. The
+// initial state is |waiting|. Once the state becomes closed or errored, it will
+// never change.
+class MODULES_EXPORT BytesConsumer : public GarbageCollectedFinalized<BytesConsumer> {
+public:
+    enum class Result {
+        Ok,
+        ShouldWait,
+        Done,
+        Error,
+    };
+    enum class State {
+        Readable,
+        Waiting,
+        Closed,
+        Errored,
+    };
+    enum class BlobSizePolicy {
+        // The returned blob must have a valid size (i.e. != kuint64max).
+        DisallowBlobWithInvalidSize,
+        // The returned blob can have an invalid size.
+        AllowBlobWithInvalidSize
+    };
+    class MODULES_EXPORT Error {
+    public:
+        Error() {}
+        explicit Error(const String& message) : m_message(message) {}
+        const String& message() const { return m_message; }
+        bool operator ==(const Error& e) const { return e.m_message == m_message; }
+
+    private:
+        String m_message;
+    };
+    // Client gets notification from the associated ByteConsumer.
+    class MODULES_EXPORT Client : public GarbageCollectedMixin {

[hiroshige, 2016/07/08 05:32:37]

Are the callbacks to Client all async?

[yhirano, 2016/07/12 10:50:57]

I recovered "This function is not called when the state change is trigerred by
public methods called by a user" statement to avoid sync notification.

+    public:
+        virtual ~Client() {}
+
+        // The associated consumer gets readable. This function will be called
+        // when the consumer was waiting but is seemingly readable now. This
+        // means that this function will not be called even when some data
+        // arrives if the consumer already has non-empty readable data.
+        // It is NOT guaranteed that the consumer is not waiting when this
+        // function is called, i.e. it can be called more than needed.
+        // One can call the associated consumer's methods in this function.
+        virtual void onReadable() = 0;
+
+        // This function will be called when the consumer was not closed but is
+        // closed now.
+        // This function will not be called when the associated consumer gets
+        // closed by BytesConsumer's public methods such as beginRead.

[hiroshige, 2016/07/08 05:32:37]

How about describing the concrete cases of when onClose() is called?
e.g.
"... gets errored by BytesConsumer's public methods, i.e. when
read()/beginRead()/endRead() returns |Done|,
drainAsBlobDataHandle()/drainAsFormData() returns non-null, or cancel() is
called."

"associated consumer gets closed by BytesConsumer's public methods" is not so
immediately clear (e.g. I missed drainAsBlobDataHandle() cases when I wrote this
comment at first).

Is onClose() called when the consumer is already closed when setClient() is
called?

[yhirano, 2016/07/12 10:50:57]

Hmm, I'm not sure if it helps users. And I think such statements are likely to
be stale.
No.

+        virtual void onClose() = 0;
+
+        // This function will be called when the consumer was not errored but is
+        // errored now.
+        // This function will not be called when the associated consumer gets
+        // errored by BytesConsumer's public methods such as beginRead.

[hiroshige, 2016/07/08 05:32:37]

Ditto.

From the comments, drainAsBlobDataHandle()/drainAsFormData()/cancel() never
causes the consumer to be errored, right?

[yhirano, 2016/07/12 10:50:57]

ditto

+        virtual void onError(const Error&) = 0;
+    };
+
+    virtual ~BytesConsumer() {}
+
+    // Reads data into |buffer| up to |size| bytes. The actual read size will
+    // be stored in |*readSize|. This function cannot be called when a two-phase
+    // read is in progress.
+    // Returns Ok when readable.
+    // Returns ShouldWait when it's waiting.
+    // Returns Done when closed.
+    // Returns Error when errored.
+    virtual Result read(char* buffer, size_t /* size */, size_t* readSize);

[hiroshige, 2016/07/08 05:32:37]

Do we allow |buffer| == nullptr when |size| == 0?
Do we allow returning |Ok| with |size| == 0?
Is |*readSize| always set to 0 when returned value is not |Ok|?

I expect these are all true, and if so I want these to be clarified in the
comment.

[yhirano, 2016/07/12 10:50:57]

true/false/true

+
+    // Begins a two-phase read. On success, the function stores a buffer
+    // that contains the read data of length |*available| into |*buffer|.
+    // Returns Ok when readable.
+    // Returns ShouldWait when it's waiting.
+    // Returns Done when it's closed.
+    // Returns Error when errored.
+    // When not readable, the caller don't have to (and must not) call
+    // endRead, because the read session implicitly ends in that case.
+    virtual Result beginRead(const char** buffer, size_t* available) = 0;

[hiroshige, 2016/07/08 05:32:37]

Do we allow returning |Ok| with |*avaliable| == 0?
Do we allow (or enforce?) |*buffer| == nullptr when |*available| == 0?
Is |*available| always set to 0 when returned value is not |Ok|?

[yhirano, 2016/07/12 10:50:57]

true/true/true

+
+    // Ends a two-phase read.
+    virtual Result endRead(size_t readSize) = 0;
+
+    // Drains the data as a BlobDataHandle.
+    // When this function returns a non-null value, the returned blob handle
+    // contains bytes that would be read through read, beginRead and
+    // endRead functions without calling this function. In such a case, this
+    // object becomes closed.
+    // When this function returns null value, this function does nothing.
+    // When |policy| is DisallowBlobWithInvalidSize, this function doesn't
+    // return a non-null blob handle with unspecified size.
+    // The type of the returned handle may not be meaningful.
+    virtual PassRefPtr<BlobDataHandle> drainAsBlobDataHandle(BlobSizePolicy = BlobSizePolicy::DisallowBlobWithInvalidSize) { return nullptr; }
+
+    // Drains the data as an EncodedFormData.
+    // When this function returns a non-null value, the returned form data
+    // contains bytes that would be read through read, beginRead and
+    // endRead functions without calling this function. In such a case, this
+    // object becomes closed.
+    // When this function returns null value, this function does nothing.
+    // This function returns a non-null form data when the handle is made
+    // from an EncodedFormData-convertible value.
+    virtual PassRefPtr<EncodedFormData> drainAsFormData() { return nullptr; }
+
+    // Sets a client. At most one client can be set on a BytesConsumer.
+    virtual void setClient(Client*) = 0;
+    // Clears the set client. This can be called only when a client is set.
+    virtual void clearClient() = 0;
+
+    // Cancels this ByteConsumer. This function does nothing when |this| is
+    // already closed or errored. Otherwise, this object becomes closed.
+    virtual void cancel() = 0;
+
+    // Returns the associated error of this object. This function can be called
+    // only when errored.
+    virtual Error getError() const = 0;
+
+    // Each implementation should return a string that represents the
+    // implementation for debug purpose.
+    virtual String debugName() const = 0;
+
+    DEFINE_INLINE_VIRTUAL_TRACE() {}
+};
+
+} // namespace blink
+
+#endif // BytesConsumer_h