[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. Once
+// the state becomes closed or errored, it will never change. |reading| means

[hiroshige, 2016/07/26 06:48:11]

Isn't it |readable|?

[yhirano, 2016/07/27 13:19:52]

Done.

+// that the BytesConsumer is ready to read non-empty bytes synchronously.
+class MODULES_EXPORT BytesConsumer : public GarbageCollectedFinalized<BytesConsumer> {
+public:
+    enum class Result {
+        Ok,
+        ShouldWait,
+        Done,
+        Error,
+    };
+    // Readable and Waiting are indistinguishable from BytesConsumer users.
+    enum class PublicState {
+        ReadableOrWaiting,
+        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 {
+    public:
+        virtual ~Client() {}
+
+        // This function is called when the state changes. This function can

[hiroshige, 2016/07/26 06:48:11]

nit: "the state" is slightly ambiguous: PublicState or InternalState.

[yhirano, 2016/07/27 13:19:52]

The master definition is at (L21-L22). "state" there is an abstract idea, and
both InternalState and PublicState are concrete enums in C++.

+        // be called more than needed, i.e., it can be called even when the
+        // state is not actually changed.
+        //
+        // This function is not called when the state change is trigerred by
+        // public methods called by a user. For example, when a user reads
+        // data by |read| and the state changes from waiting to readable, this
+        // function will not be called.
+        virtual void onStateChange() = 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.
+    // |buffer| can be null if |size| is 0.
+    // |*readSize| will be set to 0 if not readable.
+    virtual Result read(char* buffer, size_t /* size */, size_t* readSize);
+
+    // 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.
+    //
+    // |*buffer| will be set to null and |*available| will be set to 0 if not
+    // readable.
+    virtual Result beginRead(const char** buffer, size_t* available) = 0;
+
+    // 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.

[hiroshige, 2016/07/26 06:48:11]

nit: "The type" here is slightly ambiguous: BlobDataHandle::type(), or the type
of returned value (==BlobDataHandle).

[yhirano, 2016/07/27 13:19:52]

Is it clearer now?

+    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.
+    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 current state.
+    virtual PublicState getPublicState() const = 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() {}
+
+protected:
+    // This InternalState directly corresponds to the states in the class
+    // comments. This enum is defined here for subclasses.
+    enum class InternalState {
+        Readable,
+        Waiting,
+        Closed,
+        Errored,
+    };
+
+    static PublicState getPublicStateFromInternalState(InternalState state)
+    {
+        switch (state) {
+        case InternalState::Readable:
+        case InternalState::Waiting:
+            return PublicState::ReadableOrWaiting;
+        case InternalState::Closed:
+            return PublicState::Closed;
+        case InternalState::Errored:
+            return PublicState::Errored;
+        }
+        NOTREACHED();
+        return PublicState::ReadableOrWaiting;
+    }
+};
+
+} // namespace blink
+
+#endif // BytesConsumer_h