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..3110f86b29b81e84c4cbe8be8b71a36f8e612c74 100644
--- a/public/platform/WebDataConsumerHandle.h
+++ b/public/platform/WebDataConsumerHandle.h
@@ -7,20 +7,22 @@
 
 #include <stddef.h>
 
+#if INSIDE_BLINK
+#include "wtf/PassOwnPtr.h"
+#else
+#include <base/memory/scoped_ptr.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 having a reader is called "locked".
 class WebDataConsumerHandle {
 public:
-    // This corresponds to MojoReadDataFlags.
     using Flags = unsigned;
     static const Flags FlagNone = 0;
 
@@ -41,8 +43,60 @@ public:
         virtual void didGetReadable() = 0;

[hiroshige, 2015/06/09 14:26:24]

As discussed offline briefly, we have to define when did this notification is
fired more clearly (related to the comment about the state diagram above).

Some specific questions:
- When we do partial read (i.e. call endRead() with size < *available returned
by beginRead()), the handle remains still 'readable' (because there are still
remaining bytes). When didGetReadable() is called next? Immediately or when the
next data arrives?
- Can we assume read() returns Ok or Done when didGetReadable() is called? (I
assume No, allowing redundant notifications would simplify implementation)

[hiroshige, 2015/06/09 14:26:24]

Also, I'd like state reentrancy explicitly, e.g. "in didGetReadable() we can
call read()/beginRead()/endRead() or destruct handle/reader;
read()/beginRead()/endRead()/dtors of handle/read don't call didGeadReadable()
synchronously, thus didGetReadable() is not called recursively." etc. (I'm not
sure my assumption above is correct though)

[yhirano, 2015/06/10 11:10:27]

Done.

[yhirano, 2015/06/10 11:10:27]

Done.

     };
 
+    // 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.
+    // A reader can outlive the associated handle. In such a case, the handle
+    // destruction will not affect the reader functionality.
+    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

[hiroshige, 2015/06/09 14:26:24]

Is |*readSize| always valid? (i.e. even in the case of failure?)

[yhirano, 2015/06/10 11:10:26]

I added L62 but I think it is a tautology and does not make any sense.

+        // two-phase read is in progress.
+        // Returns Done when it reaches to the end of the data.

[hiroshige, 2015/06/09 14:26:24]

Is |*readSize| always 0 when Done?

[yhirano, 2015/06/10 11:10:26]

Done.

+        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

[hiroshige, 2015/06/09 14:26:24]

What is "success"? i.e. Result == Ok || Done?
If not successful, are the values of |*buffer| and |*available|
unspecified/undefined?

[yhirano, 2015/06/10 11:10:26]

Done.

+        // that contains the read data of length |*available| into |*buffer|.
+        // Returns Done when it reaches to the end of the data.

[hiroshige, 2015/06/09 14:26:24]

When Done, |*available| can be non-zero?

[yhirano, 2015/06/10 11:10:27]

Done.

+        // 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 only when this handle is
+    // not locked. |client| can be null. Otherwise, |*client| must be
+    // valid as long as the reader is valid. The returned reader is bound to
+    // the calling thread and client notification will be called on the thread
+    // if |client| is not null.
+#if INSIDE_BLINK
+    PassOwnPtr<Reader> obtainReader(Client* client) { return adoptPtr(obtainReaderInternal(client)); }
+#else
+    scoped_ptr<Reader> obtainReader(Client* client) { return scoped_ptr<Reader>(obtainReaderInternal(client)); }
+#endif
+
+private:
+    // The caller takes ownership of the returned object.
+    virtual Reader* obtainReaderInternal(Client* client) { return nullptr; }
+
+    // Below are deprecated functions that will be removed shortly. Use Reader
+    // instead.
+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.