third_party/WebKit/public/platform/WebDataConsumerHandle.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef WebDataConsumerHandle_h
   6 #define WebDataConsumerHandle_h
   7
   8 #include <stddef.h>
   9
  10 #if INSIDE_BLINK
  11 #include "wtf/PassOwnPtr.h"
  12 #endif
  13
  14 #include "public/platform/WebCommon.h"
  15
  16 namespace blink {
  17
  18 // WebDataConsumerHandle represents the "consumer" side of a data pipe. A user
  19 // can read data from it.
  20 //
  21 // A WebDataConsumerHandle is a thread-safe object. A user can call
  22 // |obtainReader| or destruct the object on any thread.
  23 // A WebDataConsumerHandle having a reader is called "locked". A
  24 // WebDataConsumerHandle or its reader are called "waiting" when reading from
  25 // the handle or reader returns ShouldWait.
  26 //
  27 // WebDataConsumerHandle can be created / used / destructed only on
  28 // Oilpan-enabled threads.
  29 // TODO(yhirano): Remove this restriction.
  30 class BLINK_PLATFORM_EXPORT WebDataConsumerHandle {
  31 public:
  32     using Flags = unsigned;
  33     static const Flags FlagNone = 0;
  34
  35     enum Result {
  36         Ok,
  37         Done,
  38         Busy,
  39         ShouldWait,
  40         ResourceExhausted,
  41         UnexpectedError,
  42     };
  43
  44     // Client gets notification from the pipe.
  45     class BLINK_PLATFORM_EXPORT Client {
  46     public:
  47         virtual ~Client() { }
  48         // The associated handle gets readable. This function will be called
  49         // when the associated reader was waiting but is not waiting any more.
  50         // This means this function can be called when handle gets errored or
  51         // closed. This also means that this function will not be called even
  52         // when some data arrives if the handle already has non-empty readable
  53         // data.
  54         // It is not guaranteed that the handle is not waiting when this
  55         // function is called, i.e. it can be called more than needed.
  56         // One can use / destruct the associated reader in this function.
  57         virtual void didGetReadable() = 0;
  58     };
  59
  60     // This class provides a means to read data from the associated handle. A
  61     // Reader object is bound to the thread on which |obtainReader| is called.
  62     // Any functions including the destructor should be called on the thread.
  63     // A reader can outlive the associated handle. In such a case, the handle
  64     // destruction will not affect the reader functionality.
  65     // Reading functions may success (i.e. return Ok) or fail (otherwise), and
  66     // the behavior which is not specified is unspecified.
  67     class Reader {
  68     public:
  69         // Destructing a reader means it is released and a user can get another
  70         // Reader by calling |obtainReader| on any thread again.
  71         virtual ~Reader() { }
  72
  73         // Reads data into |data| up to |size| bytes. The actual read size will
  74         // be stored in |*readSize|. This function cannot be called when a
  75         // two-phase read is in progress.
  76         // Returns Done when it reaches to the end of the data.
  77         // Returns ShouldWait when the handle does not have data to read but
  78         // it is not closed or errored.
  79         virtual Result read(void* data, size_t /* size */, Flags, size_t* readSize)
  80         {
  81             BLINK_ASSERT_NOT_REACHED();
  82             return UnexpectedError;
  83         }
  84
  85         // Begins a two-phase read. On success, the function stores a buffer
  86         // that contains the read data of length |*available| into |*buffer|.
  87         // Returns Done when it reaches to the end of the data.
  88         // Returns ShouldWait when the handle does not have data to read but
  89         // it is not closed or errored.
  90         // On fail, you don't have to (and should not) call endRead, because the
  91         // read session implicitly ends in that case.
  92         virtual Result beginRead(const void** buffer, Flags, size_t* available)
  93         {
  94             BLINK_ASSERT_NOT_REACHED();
  95             return UnexpectedError;
  96         }
  97
  98         // Ends a two-phase read.
  99         // |readSize| indicates the actual read size.
 100         virtual Result endRead(size_t readSize)
 101         {
 102             BLINK_ASSERT_NOT_REACHED();
 103             return UnexpectedError;
 104         }
 105     };
 106
 107     WebDataConsumerHandle();
 108     virtual ~WebDataConsumerHandle();
 109
 110     // Returns a non-null reader. This function can be called only when this
 111     // handle is not locked. |client| can be null. Otherwise, |*client| must be
 112     // valid as long as the reader is valid. The returned reader is bound to
 113     // the calling thread and client notification will be called on the thread
 114     // if |client| is not null.
 115     // If |client| is not null and the handle is not waiting, client
 116     // notification is called asynchronously.
 117 #if INSIDE_BLINK
 118     PassOwnPtr<Reader> obtainReader(Client*);
 119 #endif
 120
 121     // Returns a string literal (e.g. class name) for debugging only.
 122     virtual const char* debugName() const { return "WebDataConsumerHandle"; }
 123
 124 private:
 125     // The caller takes ownership of the returned object.
 126     virtual Reader* obtainReaderInternal(Client* client)
 127     {
 128         BLINK_ASSERT_NOT_REACHED();
 129         return nullptr;
 130     }
 131 };
 132
 133 } // namespace blink
 134
 135 #endif // WebDataConsumerHandle_h