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 15 namespace 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. 73 class 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. 96 class 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. 114 class NET_EXPORT StringIOBuffer : public IOBuffer { 115 public: 116 explicit StringIOBuffer(const std::string& s); 117 118 int size() const { return static_cast<int>(string_data_.size()); } 119 120 private: 121 virtual ~StringIOBuffer(); 122 123 std::string string_data_; 124 }; 125 126 // This version wraps an existing IOBuffer and provides convenient functions 127 // to progressively read all the data. 128 // 129 // DrainableIOBuffer is useful when you have an IOBuffer that contains data 130 // to be written progressively, and Write() function takes an IOBuffer rather 131 // than char*. DrainableIOBuffer can be used as follows: 132 // 133 // // payload is the IOBuffer containing the data to be written. 134 // buf = new DrainableIOBuffer(payload, payload_size); 135 // 136 // while (buf->BytesRemaining() > 0) { 137 // // Write() takes an IOBuffer. If it takes char*, we could 138 // // simply use the regular IOBuffer like payload->data() + offset. 139 // int bytes_written = Write(buf, buf->BytesRemaining()); 140 // buf->DidConsume(bytes_written); 141 // } 142 // 143 class NET_EXPORT DrainableIOBuffer : public IOBuffer { 144 public: 145 DrainableIOBuffer(IOBuffer* base, int size); 146 147 // DidConsume() changes the |data_| pointer so that |data_| always points 148 // to the first unconsumed byte. 149 void DidConsume(int bytes); 150 151 // Returns the number of unconsumed bytes. 152 int BytesRemaining() const; 153 154 // Returns the number of consumed bytes. 155 int BytesConsumed() const; 156 157 // Seeks to an arbitrary point in the buffer. The notion of bytes consumed 158 // and remaining are updated appropriately. 159 void SetOffset(int bytes); 160 161 int size() const { return size_; } 162 163 private: 164 virtual ~DrainableIOBuffer(); 165 166 scoped_refptr<IOBuffer> base_; 167 int size_; 168 int used_; 169 }; 170 171 // This version provides a resizable buffer and a changeable offset. 172 // 173 // GrowableIOBuffer is useful when you read data progressively without 174 // knowing the total size in advance. GrowableIOBuffer can be used as 175 // follows: 176 // 177 // buf = new GrowableIOBuffer; 178 // buf->SetCapacity(1024); // Initial capacity. 179 // 180 // while (!some_stream->IsEOF()) { 181 // // Double the capacity if the remaining capacity is empty. 182 // if (buf->RemainingCapacity() == 0) 183 // buf->SetCapacity(buf->capacity() * 2); 184 // int bytes_read = some_stream->Read(buf, buf->RemainingCapacity()); 185 // buf->set_offset(buf->offset() + bytes_read); 186 // } 187 // 188 class NET_EXPORT GrowableIOBuffer : public IOBuffer { 189 public: 190 GrowableIOBuffer(); 191 192 // realloc memory to the specified capacity. 193 void SetCapacity(int capacity); 194 int capacity() { return capacity_; } 195 196 // |offset| moves the |data_| pointer, allowing "seeking" in the data. 197 void set_offset(int offset); 198 int offset() { return offset_; } 199 200 int RemainingCapacity(); 201 char* StartOfBuffer(); 202 203 private: 204 virtual ~GrowableIOBuffer(); 205 206 scoped_ptr_malloc<char> real_data_; 207 int capacity_; 208 int offset_; 209 }; 210 211 // This versions allows a pickle to be used as the storage for a write-style 212 // operation, avoiding an extra data copy. 213 class NET_EXPORT PickledIOBuffer : public IOBuffer { 214 public: 215 PickledIOBuffer(); 216 217 Pickle* pickle() { return &pickle_; } 218 219 // Signals that we are done writing to the pickle and we can use it for a 220 // write-style IO operation. 221 void Done(); 222 223 private: 224 virtual ~PickledIOBuffer(); 225 226 Pickle pickle_; 227 }; 228 229 // This class allows the creation of a temporary IOBuffer that doesn't really 230 // own the underlying buffer. Please use this class only as a last resort. 231 // A good example is the buffer for a synchronous operation, where we can be 232 // sure that nobody is keeping an extra reference to this object so the lifetime 233 // of the buffer can be completely managed by its intended owner. 234 class NET_EXPORT WrappedIOBuffer : public IOBuffer { 235 public: 236 explicit WrappedIOBuffer(const char* data); 237 238 protected: 239 virtual ~WrappedIOBuffer(); 240 }; 241 242 } // namespace net 243 244 #endif // NET_BASE_IO_BUFFER_H_ 245