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"
+#else
+#include <base/memory/scoped_ptr.h>

[tkent, 2015/06/12 07:51:49]

We don't allow base/ dependency yet  though there are some exceptions.

[yhirano, 2015/06/12 08:13:13]

Done.

+#endif
+
+#include "public/platform/WebCommon.h"
+
 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". A
+// WebDataConsumerHandle or its reader are called "waiting" when reading from
+// the handle or reader returns ShouldWait.
 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.
+        // The associated handle gets readable. This function will be called
+        // when the associated reader was waiting but is not waiting any more.
+        // This means this function can be called when handle gets errored or
+        // closed. This also means that this function will not be called even
+        // when some data arrives if the handle already has non-empty readable
+        // data.
+        // It is not guaranteed that the handle is not waiting when this
+        // function is called, i.e. it can be called more than needed.
+        // One can use / destruct the associated reader in this function.
         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.
+    // A reader can outlive the associated handle. In such a case, the handle
+    // destruction will not affect the reader functionality.
+    // Reading functions may success (i.e. return Ok) or fail (otherwise), and
+    // the behavior which is not specified is unspecified.
+    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.
+        // Returns ShouldWait when the handle does not have data to read but
+        // it is not closed or errored.
+        virtual Result read(void* data, size_t /* size */, Flags, size_t* readSize)
+        {
+            BLINK_ASSERT_NOT_REACHED();
+            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.
+        // Returns ShouldWait when the handle does not have data to read but
+        // it is not closed or errored.
+        // 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)
+        {
+            BLINK_ASSERT_NOT_REACHED();
+            return UnexpectedError;
+        }
+
+        // Ends a two-phase read.
+        // |readSize| indicates the actual read size.
+        virtual Result endRead(size_t readSize)
+        {
+            BLINK_ASSERT_NOT_REACHED();
+            return UnexpectedError;
+        }
+    };
+
     virtual ~WebDataConsumerHandle() { }
 
+    // Returns a non-null 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 |client| is not null and the handle is not waiting, client
+    // notification is called asynchronously.
+#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)
+    {
+        BLINK_ASSERT_NOT_REACHED();
+        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.
     // 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