io_buffer.h 8.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255
  1. // Copyright (c) 2012 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. #ifndef NET_BASE_IO_BUFFER_H_
  5. #define NET_BASE_IO_BUFFER_H_
  6. #include <stddef.h>
  7. #include <memory>
  8. #include <string>
  9. #include "base/memory/free_deleter.h"
  10. #include "base/memory/raw_ptr.h"
  11. #include "base/memory/ref_counted.h"
  12. #include "base/pickle.h"
  13. #include "net/base/net_export.h"
  14. namespace net {
  15. // IOBuffers are reference counted data buffers used for easier asynchronous
  16. // IO handling.
  17. //
  18. // They are often used as the destination buffers for Read() operations, or as
  19. // the source buffers for Write() operations.
  20. //
  21. // IMPORTANT: Never re-use an IOBuffer after cancelling the IO operation that
  22. // was using it, since this may lead to memory corruption!
  23. //
  24. // -----------------------
  25. // Ownership of IOBuffers:
  26. // -----------------------
  27. //
  28. // Although IOBuffers are RefCountedThreadSafe, they are not intended to be
  29. // used as a shared buffer, nor should they be used simultaneously across
  30. // threads. The fact that they are reference counted is an implementation
  31. // detail for allowing them to outlive cancellation of asynchronous
  32. // operations.
  33. //
  34. // Instead, think of the underlying |char*| buffer contained by the IOBuffer
  35. // as having exactly one owner at a time.
  36. //
  37. // Whenever you call an asynchronous operation that takes an IOBuffer,
  38. // ownership is implicitly transferred to the called function, until the
  39. // operation has completed (at which point it transfers back to the caller).
  40. //
  41. // ==> The IOBuffer's data should NOT be manipulated, destroyed, or read
  42. // until the operation has completed.
  43. //
  44. // ==> Cancellation does NOT count as completion. If an operation using
  45. // an IOBuffer is cancelled, the caller should release their
  46. // reference to this IOBuffer at the time of cancellation since
  47. // they can no longer use it.
  48. //
  49. // For instance, if you were to call a Read() operation on some class which
  50. // takes an IOBuffer, and then delete that class (which generally will
  51. // trigger cancellation), the IOBuffer which had been passed to Read() should
  52. // never be re-used.
  53. //
  54. // This usage contract is assumed by any API which takes an IOBuffer, even
  55. // though it may not be explicitly mentioned in the function's comments.
  56. //
  57. // -----------------------
  58. // Motivation
  59. // -----------------------
  60. //
  61. // The motivation for transferring ownership during cancellation is
  62. // to make it easier to work with un-cancellable operations.
  63. //
  64. // For instance, let's say under the hood your API called out to the
  65. // operating system's synchronous ReadFile() function on a worker thread.
  66. // When cancelling through our asynchronous interface, we have no way of
  67. // actually aborting the in progress ReadFile(). We must let it keep running,
  68. // and hence the buffer it was reading into must remain alive. Using
  69. // reference counting we can add a reference to the IOBuffer and make sure
  70. // it is not destroyed until after the synchronous operation has completed.
  71. class NET_EXPORT IOBuffer : public base::RefCountedThreadSafe<IOBuffer> {
  72. public:
  73. IOBuffer();
  74. explicit IOBuffer(size_t buffer_size);
  75. char* data() const { return data_; }
  76. protected:
  77. friend class base::RefCountedThreadSafe<IOBuffer>;
  78. static void AssertValidBufferSize(size_t size);
  79. static void AssertValidBufferSize(int size);
  80. // Only allow derived classes to specify data_.
  81. // In all other cases, we own data_, and must delete it at destruction time.
  82. explicit IOBuffer(char* data);
  83. virtual ~IOBuffer();
  84. raw_ptr<char> data_;
  85. };
  86. // This version stores the size of the buffer so that the creator of the object
  87. // doesn't have to keep track of that value.
  88. // NOTE: This doesn't mean that we want to stop sending the size as an explicit
  89. // argument to IO functions. Please keep using IOBuffer* for API declarations.
  90. class NET_EXPORT IOBufferWithSize : public IOBuffer {
  91. public:
  92. explicit IOBufferWithSize(size_t size);
  93. int size() const { return size_; }
  94. protected:
  95. // Purpose of this constructor is to give a subclass access to the base class
  96. // constructor IOBuffer(char*) thus allowing subclass to use underlying
  97. // memory it does not own.
  98. IOBufferWithSize(char* data, size_t size);
  99. ~IOBufferWithSize() override;
  100. int size_;
  101. };
  102. // This is a read only IOBuffer. The data is stored in a string and
  103. // the IOBuffer interface does not provide a proper way to modify it.
  104. class NET_EXPORT StringIOBuffer : public IOBuffer {
  105. public:
  106. explicit StringIOBuffer(const std::string& s);
  107. explicit StringIOBuffer(std::unique_ptr<std::string> s);
  108. int size() const { return static_cast<int>(string_data_.size()); }
  109. private:
  110. ~StringIOBuffer() override;
  111. std::string string_data_;
  112. };
  113. // This version wraps an existing IOBuffer and provides convenient functions
  114. // to progressively read all the data.
  115. //
  116. // DrainableIOBuffer is useful when you have an IOBuffer that contains data
  117. // to be written progressively, and Write() function takes an IOBuffer rather
  118. // than char*. DrainableIOBuffer can be used as follows:
  119. //
  120. // // payload is the IOBuffer containing the data to be written.
  121. // buf = base::MakeRefCounted<DrainableIOBuffer>(payload, payload_size);
  122. //
  123. // while (buf->BytesRemaining() > 0) {
  124. // // Write() takes an IOBuffer. If it takes char*, we could
  125. // // simply use the regular IOBuffer like payload->data() + offset.
  126. // int bytes_written = Write(buf, buf->BytesRemaining());
  127. // buf->DidConsume(bytes_written);
  128. // }
  129. //
  130. class NET_EXPORT DrainableIOBuffer : public IOBuffer {
  131. public:
  132. // TODO(eroman): Deprecated. Use the size_t flavor instead. crbug.com/488553
  133. DrainableIOBuffer(scoped_refptr<IOBuffer> base, int size);
  134. DrainableIOBuffer(scoped_refptr<IOBuffer> base, size_t size);
  135. // DidConsume() changes the |data_| pointer so that |data_| always points
  136. // to the first unconsumed byte.
  137. void DidConsume(int bytes);
  138. // Returns the number of unconsumed bytes.
  139. int BytesRemaining() const;
  140. // Returns the number of consumed bytes.
  141. int BytesConsumed() const;
  142. // Seeks to an arbitrary point in the buffer. The notion of bytes consumed
  143. // and remaining are updated appropriately.
  144. void SetOffset(int bytes);
  145. int size() const { return size_; }
  146. private:
  147. ~DrainableIOBuffer() override;
  148. scoped_refptr<IOBuffer> base_;
  149. int size_;
  150. int used_ = 0;
  151. };
  152. // This version provides a resizable buffer and a changeable offset.
  153. //
  154. // GrowableIOBuffer is useful when you read data progressively without
  155. // knowing the total size in advance. GrowableIOBuffer can be used as
  156. // follows:
  157. //
  158. // buf = base::MakeRefCounted<GrowableIOBuffer>();
  159. // buf->SetCapacity(1024); // Initial capacity.
  160. //
  161. // while (!some_stream->IsEOF()) {
  162. // // Double the capacity if the remaining capacity is empty.
  163. // if (buf->RemainingCapacity() == 0)
  164. // buf->SetCapacity(buf->capacity() * 2);
  165. // int bytes_read = some_stream->Read(buf, buf->RemainingCapacity());
  166. // buf->set_offset(buf->offset() + bytes_read);
  167. // }
  168. //
  169. class NET_EXPORT GrowableIOBuffer : public IOBuffer {
  170. public:
  171. GrowableIOBuffer();
  172. // realloc memory to the specified capacity.
  173. void SetCapacity(int capacity);
  174. int capacity() { return capacity_; }
  175. // |offset| moves the |data_| pointer, allowing "seeking" in the data.
  176. void set_offset(int offset);
  177. int offset() { return offset_; }
  178. int RemainingCapacity();
  179. char* StartOfBuffer();
  180. private:
  181. ~GrowableIOBuffer() override;
  182. std::unique_ptr<char, base::FreeDeleter> real_data_;
  183. int capacity_ = 0;
  184. int offset_ = 0;
  185. };
  186. // This versions allows a pickle to be used as the storage for a write-style
  187. // operation, avoiding an extra data copy.
  188. class NET_EXPORT PickledIOBuffer : public IOBuffer {
  189. public:
  190. PickledIOBuffer();
  191. base::Pickle* pickle() { return &pickle_; }
  192. // Signals that we are done writing to the pickle and we can use it for a
  193. // write-style IO operation.
  194. void Done();
  195. private:
  196. ~PickledIOBuffer() override;
  197. base::Pickle pickle_;
  198. };
  199. // This class allows the creation of a temporary IOBuffer that doesn't really
  200. // own the underlying buffer. Please use this class only as a last resort.
  201. // A good example is the buffer for a synchronous operation, where we can be
  202. // sure that nobody is keeping an extra reference to this object so the lifetime
  203. // of the buffer can be completely managed by its intended owner.
  204. class NET_EXPORT WrappedIOBuffer : public IOBuffer {
  205. public:
  206. explicit WrappedIOBuffer(const char* data);
  207. protected:
  208. ~WrappedIOBuffer() override;
  209. };
  210. } // namespace net
  211. #endif // NET_BASE_IO_BUFFER_H_