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