Add WebDataConsumerHandle::Reader interface.

public/platform/WebDataConsumerHandle.h

Index: public/platform/WebDataConsumerHandle.h
diff --git a/public/platform/WebDataConsumerHandle.h b/public/platform/WebDataConsumerHandle.h
index 37d14d1390effb6c69fa1ca3784bf91e191b99e5..843ae3c55c8abc51c3120d6f5563007eb52b71d7 100644
--- a/public/platform/WebDataConsumerHandle.h
+++ b/public/platform/WebDataConsumerHandle.h
@@ -7,20 +7,20 @@
 
 #include <stddef.h>
 
+#if INSIDE_BLINK
+#include "wtf/PassOwnPtr.h"
+#endif
+
 namespace blink {
 
 // WebDataConsumerHandle represents the "consumer" side of a data pipe. A user
 // can read data from it.
-// This data type is basically a wrapper of mojo data pipe consumer handle.
-// See mojo/public/c/system/data_pipe.h for details.
 //
-// Note:
-//  - If you register a client, all of read / beginRead / endRead /
-//    registerClient / unregisterClient must be called on the same thread.
-//    Client notification is called on the thread.
+// A WebDataConsumerHandle is a thread-safe object. A user can call
+// |obtainReader| or destruct the object on any thread.
+// A WebDataConsumerHandle which has an active reader is called "locked".

[hiroshige, 2015/06/04 10:06:14]

nit: the word "active reader" might be confusing (i.e. there's no method like
Reader::isActive(). how about just "reader"?)

Mention that a Reader can outlive corresponding WebDataConsumerHandle, and can
be used until Reader's destruction even WebDataConsumerHandle is already
destructed.

[yhirano, 2015/06/04 12:04:09]

Done.

 class WebDataConsumerHandle {
 public:
-    // This corresponds to MojoReadDataFlags.
     using Flags = unsigned;
     static const Flags FlagNone = 0;
 
@@ -41,8 +41,53 @@ public:
         virtual void didGetReadable() = 0;
     };
 
+    // This class provides a means to read data from the associated handle. A
+    // Reader object is bound to the thread on which |obtainReader| is called.
+    // Any functions including the destructor should be called on the thread.
+    class Reader {
+    public:
+        // Destructing a reader means it is released and a user can get another
+        // Reader by calling |obtainReader| on any thread again.
+        virtual ~Reader() { }
+
+        // Reads data into |data| 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 Done when it reaches to the end of the data.
+        virtual Result read(void* data, size_t /* size */, Flags, size_t* readSize) { return UnexpectedError; }
+
+        // Begins a two-phase read. On success, the function stores a buffer
+        // that contains the read data of length |*available| into |*buffer|.
+        // Returns Done when it reaches to the end of the data.
+        // On fail, you don't have to (and should not) call endRead, because the
+        // read session implicitly ends in that case.
+        virtual Result beginRead(const void** buffer, Flags, size_t* available) { return UnexpectedError; }
+
+        // Ends a two-phase read.
+        // |readSize| indicates the actual read size.
+        virtual Result endRead(size_t readSize) { return UnexpectedError; }
+    };
+
     virtual ~WebDataConsumerHandle() { }
 
+    // Returns a reader. This function can be called when there aren't any
+    // other readers. The returned reader is bound to the calling thread and

[hiroshige, 2015/06/04 10:06:15]

What occurs when there is another reader when we call obtainReader()?
- returns nullptr (I prefer this),
- or assert failure.

It might be convenient if obtainReader() returns nullptr if (and only if) there
is another reader; e.g. CompositeDataConsumerHandler might call obtainReader()
on supplied WebDataConsumerHandle, which might have a reader already.

[yhirano, 2015/06/04 12:04:09]

It is simply not allowed. I will put an assertion, but no defined behavior is
specified.

+    // client notification will be called on the thread.
+#if INSIDE_BLINK
+    PassOwnPtr<Reader> obtainReader(Client* client) { return adoptPtr(obtainReaderInternal(client)); }

[hiroshige, 2015/06/04 10:06:14]

Can |client| be nullptr? (I assume yes)

[yhirano, 2015/06/04 12:04:09]

Done.

+#endif
+
+private:
+    // The caller takes ownership of the returned object.
+    virtual Reader* obtainReaderInternal(Client* client) { return nullptr; }
+
+    // Below are deprecated functions. Use Reader instaed.
+public:
+    // Note: read / beginRead / endRead / unregisterClient must not be called
+    // when a client is regsitered. They must be called on the thread on which
+    // registerClient is called. registerClient must not be called when a client
+    // is already registered.
+
     // Reads data into |data| 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.