Add WebDataConsumerHandle::Reader interface.

public/platform/WebDataConsumerHandle.h

 // Copyright 2014 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 WebDataConsumerHandle_h
 #define WebDataConsumerHandle_h
 
 #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;
 
     enum Result {
         Ok,
         Done,
         Busy,
         ShouldWait,
         ResourceExhausted,
         UnexpectedError,
     };
 
     // Client gets notification from the pipe.
     class Client {
     public:
         virtual ~Client() { }
         // The associated handle gets readable.
         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.
     // 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; }
 
     // Registers |client| to this handle. The client must not be null and must
     // be valid until it is unregistered (or the handle is destructed).
     // Only one registration can be made for a handle at a time.
     virtual void registerClient(Client* /* client */)  { }
 
     // Unregisters |client| from this handle.
     virtual void unregisterClient() { }
 };
 
 } // namespace blink
 
 #endif // WebDataConsumerHandle_h