2 * Copyright 2014 Facebook, Inc.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 #ifndef FOLLY_IO_IOBUF_H_
18 #define FOLLY_IO_IOBUF_H_
20 #include <glog/logging.h>
29 #include <type_traits>
31 #include <boost/iterator/iterator_facade.hpp>
33 #include "folly/FBString.h"
34 #include "folly/Range.h"
35 #include "folly/FBVector.h"
37 // Ignore shadowing warnings within this file, so includers can use -Wshadow.
38 #pragma GCC diagnostic push
39 #pragma GCC diagnostic ignored "-Wshadow"
44 * An IOBuf is a pointer to a buffer of data.
46 * IOBuf objects are intended to be used primarily for networking code, and are
47 * modelled somewhat after FreeBSD's mbuf data structure, and Linux's sk_buff
50 * IOBuf objects facilitate zero-copy network programming, by allowing multiple
51 * IOBuf objects to point to the same underlying buffer of data, using a
52 * reference count to track when the buffer is no longer needed and can be
59 * The IOBuf itself is a small object containing a pointer to the buffer and
60 * information about which segment of the buffer contains valid data.
62 * The data layout looks like this:
70 * +------------+--------------------+-----------+
71 * | headroom | data | tailroom |
72 * +------------+--------------------+-----------+
74 * buffer() data() tail() bufferEnd()
76 * The length() method returns the length of the valid data; capacity()
77 * returns the entire capacity of the buffer (from buffer() to bufferEnd()).
78 * The headroom() and tailroom() methods return the amount of unused capacity
79 * available before and after the data.
85 * The buffer itself is reference counted, and multiple IOBuf objects may point
86 * to the same buffer. Each IOBuf may point to a different section of valid
87 * data within the underlying buffer. For example, if multiple protocol
88 * requests are read from the network into a single buffer, a separate IOBuf
89 * may be created for each request, all sharing the same underlying buffer.
91 * In other words, when multiple IOBufs share the same underlying buffer, the
92 * data() and tail() methods on each IOBuf may point to a different segment of
93 * the data. However, the buffer() and bufferEnd() methods will point to the
94 * same location for all IOBufs sharing the same underlying buffer.
96 * +-----------+ +---------+
97 * | IOBuf 1 | | IOBuf 2 |
98 * +-----------+ +---------+
100 * data | tail |/ data | tail
102 * +-------------------------------------+
104 * +-------------------------------------+
106 * If you only read data from an IOBuf, you don't need to worry about other
107 * IOBuf objects possibly sharing the same underlying buffer. However, if you
108 * ever write to the buffer you need to first ensure that no other IOBufs point
109 * to the same buffer. The unshare() method may be used to ensure that you
110 * have an unshared buffer.
116 * IOBuf objects also contain pointers to next and previous IOBuf objects.
117 * This can be used to represent a single logical piece of data that its stored
118 * in non-contiguous chunks in separate buffers.
120 * A single IOBuf object can only belong to one chain at a time.
122 * IOBuf chains are always circular. The "prev" pointer in the head of the
123 * chain points to the tail of the chain. However, it is up to the user to
124 * decide which IOBuf is the head. Internally the IOBuf code does not care
125 * which element is the head.
127 * The lifetime of all IOBufs in the chain are linked: when one element in the
128 * chain is deleted, all other chained elements are also deleted. Conceptually
129 * it is simplest to treat this as if the head of the chain owns all other
130 * IOBufs in the chain. When you delete the head of the chain, it will delete
131 * the other elements as well. For this reason, prependChain() and
132 * appendChain() take ownership of of the new elements being added to this
135 * When the coalesce() method is used to coalesce an entire IOBuf chain into a
136 * single IOBuf, all other IOBufs in the chain are eliminated and automatically
137 * deleted. The unshare() method may coalesce the chain; if it does it will
138 * similarly delete all IOBufs eliminated from the chain.
140 * As discussed in the following section, it is up to the user to maintain a
141 * lock around the entire IOBuf chain if multiple threads need to access the
142 * chain. IOBuf does not provide any internal locking.
148 * When used in multithread programs, a single IOBuf object should only be used
149 * in a single thread at a time. If a caller uses a single IOBuf across
150 * multiple threads the caller is responsible for using an external lock to
151 * synchronize access to the IOBuf.
153 * Two separate IOBuf objects may be accessed concurrently in separate threads
154 * without locking, even if they point to the same underlying buffer. The
155 * buffer reference count is always accessed atomically, and no other
156 * operations should affect other IOBufs that point to the same data segment.
157 * The caller is responsible for using unshare() to ensure that the data buffer
158 * is not shared by other IOBufs before writing to it, and this ensures that
159 * the data itself is not modified in one thread while also being accessed from
162 * For IOBuf chains, no two IOBufs in the same chain should be accessed
163 * simultaneously in separate threads. The caller must maintain a lock around
164 * the entire chain if the chain, or individual IOBufs in the chain, may be
165 * accessed by multiple threads.
168 * IOBuf Object Allocation
169 * -----------------------
171 * IOBuf objects themselves exist separately from the data buffer they point
172 * to. Therefore one must also consider how to allocate and manage the IOBuf
175 * It is more common to allocate IOBuf objects on the heap, using the create(),
176 * takeOwnership(), or wrapBuffer() factory functions. The clone()/cloneOne()
177 * functions also return new heap-allocated IOBufs. The createCombined()
178 * function allocates the IOBuf object and data storage space together, in a
179 * single memory allocation. This can improve performance, particularly if you
180 * know that the data buffer and the IOBuf itself will have similar lifetimes.
182 * That said, it is also possible to allocate IOBufs on the stack or inline
183 * inside another object as well. This is useful for cases where the IOBuf is
184 * short-lived, or when the overhead of allocating the IOBuf on the heap is
187 * However, note that stack-allocated IOBufs may only be used as the head of a
188 * chain (or standalone as the only IOBuf in a chain). All non-head members of
189 * an IOBuf chain must be heap allocated. (All functions to add nodes to a
190 * chain require a std::unique_ptr<IOBuf>, which enforces this requrement.)
192 * Additionally, no copy-constructor or assignment operator currently exists,
193 * so stack-allocated IOBufs may only be moved, not copied. (Technically
194 * nothing is preventing us from adding a copy constructor and assignment
195 * operator. However, it seems like this would add the possibility for some
196 * confusion. We would need to determine if these functions would copy just a
197 * single buffer, or the entire chain.)
203 * The IOBuf class manages sharing of the underlying buffer that it points to,
204 * maintaining a reference count if multiple IOBufs are pointing at the same
207 * However, it is the callers responsibility to manage sharing and ownership of
208 * IOBuf objects themselves. The IOBuf structure does not provide room for an
209 * intrusive refcount on the IOBuf object itself, only the underlying data
210 * buffer is reference counted. If users want to share the same IOBuf object
211 * between multiple parts of the code, they are responsible for managing this
212 * sharing on their own. (For example, by using a shared_ptr. Alternatively,
213 * users always have the option of using clone() to create a second IOBuf that
214 * points to the same underlying buffer.)
217 // Is T a unique_ptr<> to a standard-layout type?
218 template <class T, class Enable=void> struct IsUniquePtrToSL
219 : public std::false_type { };
220 template <class T, class D>
221 struct IsUniquePtrToSL<
222 std::unique_ptr<T, D>,
223 typename std::enable_if<std::is_standard_layout<T>::value>::type>
224 : public std::true_type { };
225 } // namespace detail
231 enum CreateOp { CREATE };
232 enum WrapBufferOp { WRAP_BUFFER };
233 enum TakeOwnershipOp { TAKE_OWNERSHIP };
234 enum CopyBufferOp { COPY_BUFFER };
236 typedef ByteRange value_type;
237 typedef Iterator iterator;
238 typedef Iterator const_iterator;
240 typedef void (*FreeFunction)(void* buf, void* userData);
243 * Allocate a new IOBuf object with the requested capacity.
245 * Returns a new IOBuf object that must be (eventually) deleted by the
246 * caller. The returned IOBuf may actually have slightly more capacity than
249 * The data pointer will initially point to the start of the newly allocated
250 * buffer, and will have a data length of 0.
252 * Throws std::bad_alloc on error.
254 static std::unique_ptr<IOBuf> create(uint32_t capacity);
255 IOBuf(CreateOp, uint32_t capacity);
258 * Create a new IOBuf, using a single memory allocation to allocate space
259 * for both the IOBuf object and the data storage space.
261 * This saves one memory allocation. However, it can be wasteful if you
262 * later need to grow the buffer using reserve(). If the buffer needs to be
263 * reallocated, the space originally allocated will not be freed() until the
264 * IOBuf object itself is also freed. (It can also be slightly wasteful in
265 * some cases where you clone this IOBuf and then free the original IOBuf.)
267 static std::unique_ptr<IOBuf> createCombined(uint32_t capacity);
270 * Create a new IOBuf, using separate memory allocations for the IOBuf object
271 * for the IOBuf and the data storage space.
273 * This requires two memory allocations, but saves space in the long run
274 * if you know that you will need to reallocate the data buffer later.
276 static std::unique_ptr<IOBuf> createSeparate(uint32_t capacity);
279 * Allocate a new IOBuf chain with the requested total capacity, allocating
280 * no more than maxBufCapacity to each buffer.
282 static std::unique_ptr<IOBuf> createChain(
283 size_t totalCapacity, uint32_t maxBufCapacity);
286 * Create a new IOBuf pointing to an existing data buffer.
288 * The new IOBuffer will assume ownership of the buffer, and free it by
289 * calling the specified FreeFunction when the last IOBuf pointing to this
290 * buffer is destroyed. The function will be called with a pointer to the
291 * buffer as the first argument, and the supplied userData value as the
292 * second argument. The free function must never throw exceptions.
294 * If no FreeFunction is specified, the buffer will be freed using free()
295 * which will result in undefined behavior if the memory was allocated
298 * The IOBuf data pointer will initially point to the start of the buffer,
300 * In the first version of this function, the length of data is unspecified
301 * and is initialized to the capacity of the buffer
303 * In the second version, the user specifies the valid length of data
306 * On error, std::bad_alloc will be thrown. If freeOnError is true (the
307 * default) the buffer will be freed before throwing the error.
309 static std::unique_ptr<IOBuf> takeOwnership(void* buf, uint32_t capacity,
310 FreeFunction freeFn = nullptr,
311 void* userData = nullptr,
312 bool freeOnError = true) {
313 return takeOwnership(buf, capacity, capacity, freeFn,
314 userData, freeOnError);
316 IOBuf(TakeOwnershipOp op, void* buf, uint32_t capacity,
317 FreeFunction freeFn = nullptr, void* userData = nullptr,
318 bool freeOnError = true)
319 : IOBuf(op, buf, capacity, capacity, freeFn, userData, freeOnError) {}
321 static std::unique_ptr<IOBuf> takeOwnership(void* buf, uint32_t capacity,
323 FreeFunction freeFn = nullptr,
324 void* userData = nullptr,
325 bool freeOnError = true);
326 IOBuf(TakeOwnershipOp, void* buf, uint32_t capacity, uint32_t length,
327 FreeFunction freeFn = nullptr, void* userData = nullptr,
328 bool freeOnError = true);
331 * Create a new IOBuf pointing to an existing data buffer made up of
332 * count objects of a given standard-layout type.
334 * This is dangerous -- it is essentially equivalent to doing
335 * reinterpret_cast<unsigned char*> on your data -- but it's often useful
336 * for serialization / deserialization.
338 * The new IOBuffer will assume ownership of the buffer, and free it
339 * appropriately (by calling the UniquePtr's custom deleter, or by calling
340 * delete or delete[] appropriately if there is no custom deleter)
341 * when the buffer is destroyed. The custom deleter, if any, must never
344 * The IOBuf data pointer will initially point to the start of the buffer,
345 * and the length will be the full capacity of the buffer (count *
348 * On error, std::bad_alloc will be thrown, and the buffer will be freed
349 * before throwing the error.
351 template <class UniquePtr>
352 static typename std::enable_if<detail::IsUniquePtrToSL<UniquePtr>::value,
353 std::unique_ptr<IOBuf>>::type
354 takeOwnership(UniquePtr&& buf, size_t count=1);
357 * Create a new IOBuf object that points to an existing user-owned buffer.
359 * This should only be used when the caller knows the lifetime of the IOBuf
360 * object ahead of time and can ensure that all IOBuf objects that will point
361 * to this buffer will be destroyed before the buffer itself is destroyed.
363 * This buffer will not be freed automatically when the last IOBuf
364 * referencing it is destroyed. It is the caller's responsibility to free
365 * the buffer after the last IOBuf has been destroyed.
367 * The IOBuf data pointer will initially point to the start of the buffer,
368 * and the length will be the full capacity of the buffer.
370 * An IOBuf created using wrapBuffer() will always be reported as shared.
371 * unshare() may be used to create a writable copy of the buffer.
373 * On error, std::bad_alloc will be thrown.
375 static std::unique_ptr<IOBuf> wrapBuffer(const void* buf, uint32_t capacity);
376 static std::unique_ptr<IOBuf> wrapBuffer(ByteRange br) {
377 CHECK_LE(br.size(), std::numeric_limits<uint32_t>::max());
378 return wrapBuffer(br.data(), br.size());
380 IOBuf(WrapBufferOp op, const void* buf, uint32_t capacity);
381 IOBuf(WrapBufferOp op, ByteRange br);
384 * Convenience function to create a new IOBuf object that copies data from a
385 * user-supplied buffer, optionally allocating a given amount of
386 * headroom and tailroom.
388 static std::unique_ptr<IOBuf> copyBuffer(const void* buf, uint32_t size,
390 uint32_t minTailroom=0);
391 static std::unique_ptr<IOBuf> copyBuffer(ByteRange br,
393 uint32_t minTailroom=0) {
394 CHECK_LE(br.size(), std::numeric_limits<uint32_t>::max());
395 return copyBuffer(br.data(), br.size(), headroom, minTailroom);
397 IOBuf(CopyBufferOp op, const void* buf, uint32_t size,
398 uint32_t headroom=0, uint32_t minTailroom=0);
399 IOBuf(CopyBufferOp op, ByteRange br,
400 uint32_t headroom=0, uint32_t minTailroom=0);
403 * Convenience function to create a new IOBuf object that copies data from a
404 * user-supplied string, optionally allocating a given amount of
405 * headroom and tailroom.
407 * Beware when attempting to invoke this function with a constant string
408 * literal and a headroom argument: you will likely end up invoking the
409 * version of copyBuffer() above. IOBuf::copyBuffer("hello", 3) will treat
410 * the first argument as a const void*, and will invoke the version of
411 * copyBuffer() above, with the size argument of 3.
413 static std::unique_ptr<IOBuf> copyBuffer(const std::string& buf,
415 uint32_t minTailroom=0);
416 IOBuf(CopyBufferOp op, const std::string& buf,
417 uint32_t headroom=0, uint32_t minTailroom=0)
418 : IOBuf(op, buf.data(), buf.size(), headroom, minTailroom) {}
421 * A version of copyBuffer() that returns a null pointer if the input string
424 static std::unique_ptr<IOBuf> maybeCopyBuffer(const std::string& buf,
426 uint32_t minTailroom=0);
429 * Convenience function to free a chain of IOBufs held by a unique_ptr.
431 static void destroy(std::unique_ptr<IOBuf>&& data) {
432 auto destroyer = std::move(data);
436 * Destroy this IOBuf.
438 * Deleting an IOBuf will automatically destroy all IOBufs in the chain.
439 * (See the comments above regarding the ownership model of IOBuf chains.
440 * All subsequent IOBufs in the chain are considered to be owned by the head
441 * of the chain. Users should only explicitly delete the head of a chain.)
443 * When each individual IOBuf is destroyed, it will release its reference
444 * count on the underlying buffer. If it was the last user of the buffer,
445 * the buffer will be freed.
450 * Check whether the chain is empty (i.e., whether the IOBufs in the
451 * chain have a total data length of zero).
453 * This method is semantically equivalent to
454 * i->computeChainDataLength()==0
455 * but may run faster because it can short-circuit as soon as it
456 * encounters a buffer with length()!=0
461 * Get the pointer to the start of the data.
463 const uint8_t* data() const {
468 * Get a writable pointer to the start of the data.
470 * The caller is responsible for calling unshare() first to ensure that it is
471 * actually safe to write to the buffer.
473 uint8_t* writableData() {
478 * Get the pointer to the end of the data.
480 const uint8_t* tail() const {
481 return data_ + length_;
485 * Get a writable pointer to the end of the data.
487 * The caller is responsible for calling unshare() first to ensure that it is
488 * actually safe to write to the buffer.
490 uint8_t* writableTail() {
491 return data_ + length_;
495 * Get the data length.
497 uint32_t length() const {
502 * Get the amount of head room.
504 * Returns the number of bytes in the buffer before the start of the data.
506 uint32_t headroom() const {
507 return data_ - buffer();
511 * Get the amount of tail room.
513 * Returns the number of bytes in the buffer after the end of the data.
515 uint32_t tailroom() const {
516 return bufferEnd() - tail();
520 * Get the pointer to the start of the buffer.
522 * Note that this is the pointer to the very beginning of the usable buffer,
523 * not the start of valid data within the buffer. Use the data() method to
524 * get a pointer to the start of the data within the buffer.
526 const uint8_t* buffer() const {
531 * Get a writable pointer to the start of the buffer.
533 * The caller is responsible for calling unshare() first to ensure that it is
534 * actually safe to write to the buffer.
536 uint8_t* writableBuffer() {
541 * Get the pointer to the end of the buffer.
543 * Note that this is the pointer to the very end of the usable buffer,
544 * not the end of valid data within the buffer. Use the tail() method to
545 * get a pointer to the end of the data within the buffer.
547 const uint8_t* bufferEnd() const {
548 return buf_ + capacity_;
552 * Get the total size of the buffer.
554 * This returns the total usable length of the buffer. Use the length()
555 * method to get the length of the actual valid data in this IOBuf.
557 uint32_t capacity() const {
562 * Get a pointer to the next IOBuf in this chain.
567 const IOBuf* next() const {
572 * Get a pointer to the previous IOBuf in this chain.
577 const IOBuf* prev() const {
582 * Shift the data forwards in the buffer.
584 * This shifts the data pointer forwards in the buffer to increase the
585 * headroom. This is commonly used to increase the headroom in a newly
588 * The caller is responsible for ensuring that there is sufficient
589 * tailroom in the buffer before calling advance().
591 * If there is a non-zero data length, advance() will use memmove() to shift
592 * the data forwards in the buffer. In this case, the caller is responsible
593 * for making sure the buffer is unshared, so it will not affect other IOBufs
594 * that may be sharing the same underlying buffer.
596 void advance(uint32_t amount) {
597 // In debug builds, assert if there is a problem.
598 assert(amount <= tailroom());
601 memmove(data_ + amount, data_, length_);
607 * Shift the data backwards in the buffer.
609 * The caller is responsible for ensuring that there is sufficient headroom
610 * in the buffer before calling retreat().
612 * If there is a non-zero data length, retreat() will use memmove() to shift
613 * the data backwards in the buffer. In this case, the caller is responsible
614 * for making sure the buffer is unshared, so it will not affect other IOBufs
615 * that may be sharing the same underlying buffer.
617 void retreat(uint32_t amount) {
618 // In debug builds, assert if there is a problem.
619 assert(amount <= headroom());
622 memmove(data_ - amount, data_, length_);
628 * Adjust the data pointer to include more valid data at the beginning.
630 * This moves the data pointer backwards to include more of the available
631 * buffer. The caller is responsible for ensuring that there is sufficient
632 * headroom for the new data. The caller is also responsible for populating
633 * this section with valid data.
635 * This does not modify any actual data in the buffer.
637 void prepend(uint32_t amount) {
638 DCHECK_LE(amount, headroom());
644 * Adjust the tail pointer to include more valid data at the end.
646 * This moves the tail pointer forwards to include more of the available
647 * buffer. The caller is responsible for ensuring that there is sufficient
648 * tailroom for the new data. The caller is also responsible for populating
649 * this section with valid data.
651 * This does not modify any actual data in the buffer.
653 void append(uint32_t amount) {
654 DCHECK_LE(amount, tailroom());
659 * Adjust the data pointer forwards to include less valid data.
661 * This moves the data pointer forwards so that the first amount bytes are no
662 * longer considered valid data. The caller is responsible for ensuring that
663 * amount is less than or equal to the actual data length.
665 * This does not modify any actual data in the buffer.
667 void trimStart(uint32_t amount) {
668 DCHECK_LE(amount, length_);
674 * Adjust the tail pointer backwards to include less valid data.
676 * This moves the tail pointer backwards so that the last amount bytes are no
677 * longer considered valid data. The caller is responsible for ensuring that
678 * amount is less than or equal to the actual data length.
680 * This does not modify any actual data in the buffer.
682 void trimEnd(uint32_t amount) {
683 DCHECK_LE(amount, length_);
690 * Postcondition: headroom() == 0, length() == 0, tailroom() == capacity()
693 data_ = writableBuffer();
698 * Ensure that this buffer has at least minHeadroom headroom bytes and at
699 * least minTailroom tailroom bytes. The buffer must be writable
700 * (you must call unshare() before this, if necessary).
702 * Postcondition: headroom() >= minHeadroom, tailroom() >= minTailroom,
703 * the data (between data() and data() + length()) is preserved.
705 void reserve(uint32_t minHeadroom, uint32_t minTailroom) {
706 // Maybe we don't need to do anything.
707 if (headroom() >= minHeadroom && tailroom() >= minTailroom) {
710 // If the buffer is empty but we have enough total room (head + tail),
711 // move the data_ pointer around.
713 headroom() + tailroom() >= minHeadroom + minTailroom) {
714 data_ = writableBuffer() + minHeadroom;
717 // Bah, we have to do actual work.
718 reserveSlow(minHeadroom, minTailroom);
722 * Return true if this IOBuf is part of a chain of multiple IOBufs, or false
723 * if this is the only IOBuf in its chain.
725 bool isChained() const {
726 assert((next_ == this) == (prev_ == this));
727 return next_ != this;
731 * Get the number of IOBufs in this chain.
733 * Beware that this method has to walk the entire chain.
734 * Use isChained() if you just want to check if this IOBuf is part of a chain
737 uint32_t countChainElements() const;
740 * Get the length of all the data in this IOBuf chain.
742 * Beware that this method has to walk the entire chain.
744 uint64_t computeChainDataLength() const;
747 * Insert another IOBuf chain immediately before this IOBuf.
749 * For example, if there are two IOBuf chains (A, B, C) and (D, E, F),
750 * and B->prependChain(D) is called, the (D, E, F) chain will be subsumed
751 * and become part of the chain starting at A, which will now look like
754 * Note that since IOBuf chains are circular, head->prependChain(other) can
755 * be used to append the other chain at the very end of the chain pointed to
756 * by head. For example, if there are two IOBuf chains (A, B, C) and
757 * (D, E, F), and A->prependChain(D) is called, the chain starting at A will
758 * now consist of (A, B, C, D, E, F)
760 * The elements in the specified IOBuf chain will become part of this chain,
761 * and will be owned by the head of this chain. When this chain is
762 * destroyed, all elements in the supplied chain will also be destroyed.
764 * For this reason, appendChain() only accepts an rvalue-reference to a
765 * unique_ptr(), to make it clear that it is taking ownership of the supplied
766 * chain. If you have a raw pointer, you can pass in a new temporary
767 * unique_ptr around the raw pointer. If you have an existing,
768 * non-temporary unique_ptr, you must call std::move(ptr) to make it clear
769 * that you are destroying the original pointer.
771 void prependChain(std::unique_ptr<IOBuf>&& iobuf);
774 * Append another IOBuf chain immediately after this IOBuf.
776 * For example, if there are two IOBuf chains (A, B, C) and (D, E, F),
777 * and B->appendChain(D) is called, the (D, E, F) chain will be subsumed
778 * and become part of the chain starting at A, which will now look like
781 * The elements in the specified IOBuf chain will become part of this chain,
782 * and will be owned by the head of this chain. When this chain is
783 * destroyed, all elements in the supplied chain will also be destroyed.
785 * For this reason, appendChain() only accepts an rvalue-reference to a
786 * unique_ptr(), to make it clear that it is taking ownership of the supplied
787 * chain. If you have a raw pointer, you can pass in a new temporary
788 * unique_ptr around the raw pointer. If you have an existing,
789 * non-temporary unique_ptr, you must call std::move(ptr) to make it clear
790 * that you are destroying the original pointer.
792 void appendChain(std::unique_ptr<IOBuf>&& iobuf) {
793 // Just use prependChain() on the next element in our chain
794 next_->prependChain(std::move(iobuf));
798 * Remove this IOBuf from its current chain.
800 * Since ownership of all elements an IOBuf chain is normally maintained by
801 * the head of the chain, unlink() transfers ownership of this IOBuf from the
802 * chain and gives it to the caller. A new unique_ptr to the IOBuf is
803 * returned to the caller. The caller must store the returned unique_ptr (or
804 * call release() on it) to take ownership, otherwise the IOBuf will be
805 * immediately destroyed.
807 * Since unlink transfers ownership of the IOBuf to the caller, be careful
808 * not to call unlink() on the head of a chain if you already maintain
809 * ownership on the head of the chain via other means. The pop() method
810 * is a better choice for that situation.
812 std::unique_ptr<IOBuf> unlink() {
813 next_->prev_ = prev_;
814 prev_->next_ = next_;
817 return std::unique_ptr<IOBuf>(this);
821 * Remove this IOBuf from its current chain and return a unique_ptr to
822 * the IOBuf that formerly followed it in the chain.
824 std::unique_ptr<IOBuf> pop() {
826 next_->prev_ = prev_;
827 prev_->next_ = next_;
830 return std::unique_ptr<IOBuf>((next == this) ? nullptr : next);
834 * Remove a subchain from this chain.
836 * Remove the subchain starting at head and ending at tail from this chain.
838 * Returns a unique_ptr pointing to head. (In other words, ownership of the
839 * head of the subchain is transferred to the caller.) If the caller ignores
840 * the return value and lets the unique_ptr be destroyed, the subchain will
841 * be immediately destroyed.
843 * The subchain referenced by the specified head and tail must be part of the
844 * same chain as the current IOBuf, but must not contain the current IOBuf.
845 * However, the specified head and tail may be equal to each other (i.e.,
846 * they may be a subchain of length 1).
848 std::unique_ptr<IOBuf> separateChain(IOBuf* head, IOBuf* tail) {
849 assert(head != this);
850 assert(tail != this);
852 head->prev_->next_ = tail->next_;
853 tail->next_->prev_ = head->prev_;
858 return std::unique_ptr<IOBuf>(head);
862 * Return true if at least one of the IOBufs in this chain are shared,
863 * or false if all of the IOBufs point to unique buffers.
865 * Use isSharedOne() to only check this IOBuf rather than the entire chain.
867 bool isShared() const {
868 const IOBuf* current = this;
870 if (current->isSharedOne()) {
873 current = current->next_;
874 if (current == this) {
881 * Return true if other IOBufs are also pointing to the buffer used by this
882 * IOBuf, and false otherwise.
884 * If this IOBuf points at a buffer owned by another (non-IOBuf) part of the
885 * code (i.e., if the IOBuf was created using wrapBuffer(), or was cloned
886 * from such an IOBuf), it is always considered shared.
888 * This only checks the current IOBuf, and not other IOBufs in the chain.
890 bool isSharedOne() const {
891 if (LIKELY(flags_ & (kFlagUserOwned | kFlagMaybeShared)) == 0) {
895 // If this is a user-owned buffer, it is always considered shared
896 if (flags_ & kFlagUserOwned) {
900 // kFlagMaybeShared is set, so we need to check the reference count.
901 // (Checking the reference count requires an atomic operation, which is why
902 // we prefer to only check kFlagMaybeShared if possible.)
903 DCHECK(flags_ & kFlagMaybeShared);
904 bool shared = sharedInfo_->refcount.load(std::memory_order_acquire) > 1;
906 // we're the last one left
907 flags_ &= ~kFlagMaybeShared;
913 * Ensure that this IOBuf has a unique buffer that is not shared by other
916 * unshare() operates on an entire chain of IOBuf objects. If the chain is
917 * shared, it may also coalesce the chain when making it unique. If the
918 * chain is coalesced, subsequent IOBuf objects in the current chain will be
919 * automatically deleted.
921 * Note that buffers owned by other (non-IOBuf) users are automatically
924 * Throws std::bad_alloc on error. On error the IOBuf chain will be
927 * Currently unshare may also throw std::overflow_error if it tries to
928 * coalesce. (TODO: In the future it would be nice if unshare() were smart
929 * enough not to coalesce the entire buffer if the data is too large.
930 * However, in practice this seems unlikely to become an issue.)
941 * Ensure that this IOBuf has a unique buffer that is not shared by other
944 * unshareOne() operates on a single IOBuf object. This IOBuf will have a
945 * unique buffer after unshareOne() returns, but other IOBufs in the chain
946 * may still be shared after unshareOne() returns.
948 * Throws std::bad_alloc on error. On error the IOBuf will be unmodified.
957 * Coalesce this IOBuf chain into a single buffer.
959 * This method moves all of the data in this IOBuf chain into a single
960 * contiguous buffer, if it is not already in one buffer. After coalesce()
961 * returns, this IOBuf will be a chain of length one. Other IOBufs in the
962 * chain will be automatically deleted.
964 * After coalescing, the IOBuf will have at least as much headroom as the
965 * first IOBuf in the chain, and at least as much tailroom as the last IOBuf
968 * Throws std::bad_alloc on error. On error the IOBuf chain will be
969 * unmodified. Throws std::overflow_error if the length of the entire chain
970 * larger than can be described by a uint32_t capacity.
972 * Returns ByteRange that points to the data IOBuf stores.
974 ByteRange coalesce() {
978 return ByteRange(data_, length_);
982 * Ensure that this chain has at least maxLength bytes available as a
983 * contiguous memory range.
985 * This method coalesces whole buffers in the chain into this buffer as
986 * necessary until this buffer's length() is at least maxLength.
988 * After coalescing, the IOBuf will have at least as much headroom as the
989 * first IOBuf in the chain, and at least as much tailroom as the last IOBuf
990 * that was coalesced.
992 * Throws std::bad_alloc or std::overflow_error on error. On error the IOBuf
993 * chain will be unmodified. Throws std::overflow_error if maxLength is
994 * longer than the total chain length, or if the length of the coalesced
995 * portion of the chain is larger than can be described by a uint32_t
996 * capacity. (Although maxLength is uint32_t, gather() doesn't split
997 * buffers, so coalescing whole buffers may result in a capacity that can't
998 * be described in uint32_t.
1000 * Upon return, either enough of the chain was coalesced into a contiguous
1001 * region, or the entire chain was coalesced. That is,
1002 * length() >= maxLength || !isChained() is true.
1004 void gather(uint32_t maxLength) {
1005 if (!isChained() || length_ >= maxLength) {
1008 coalesceSlow(maxLength);
1012 * Return a new IOBuf chain sharing the same data as this chain.
1014 * The new IOBuf chain will normally point to the same underlying data
1015 * buffers as the original chain. (The one exception to this is if some of
1016 * the IOBufs in this chain contain small internal data buffers which cannot
1019 std::unique_ptr<IOBuf> clone() const;
1022 * Return a new IOBuf with the same data as this IOBuf.
1024 * The new IOBuf returned will not be part of a chain (even if this IOBuf is
1025 * part of a larger chain).
1027 std::unique_ptr<IOBuf> cloneOne() const;
1030 * Return an iovector suitable for e.g. writev()
1032 * auto iov = buf->getIov();
1033 * auto xfer = writev(fd, iov.data(), iov.size());
1035 * Naturally, the returned iovector is invalid if you modify the buffer
1038 folly::fbvector<struct iovec> getIov() const;
1041 * Overridden operator new and delete.
1042 * These perform specialized memory management to help support
1043 * createCombined(), which allocates IOBuf objects together with the buffer
1046 void* operator new(size_t size);
1047 void* operator new(size_t size, void* ptr);
1048 void operator delete(void* ptr);
1051 * Destructively convert this IOBuf to a fbstring efficiently.
1052 * We rely on fbstring's AcquireMallocatedString constructor to
1055 fbstring moveToFbString();
1058 * Iteration support: a chain of IOBufs may be iterated through using
1059 * STL-style iterators over const ByteRanges. Iterators are only invalidated
1060 * if the IOBuf that they currently point to is removed.
1062 Iterator cbegin() const;
1063 Iterator cend() const;
1064 Iterator begin() const;
1065 Iterator end() const;
1068 * Allocate a new null buffer.
1070 * This can be used to allocate an empty IOBuf on the stack. It will have no
1071 * space allocated for it. This is generally useful only to later use move
1072 * assignment to fill out the IOBuf.
1077 * Move constructor and assignment operator.
1079 * In general, you should only ever move the head of an IOBuf chain.
1080 * Internal nodes in an IOBuf chain are owned by the head of the chain, and
1081 * should not be moved from. (Technically, nothing prevents you from moving
1082 * a non-head node, but the moved-to node will replace the moved-from node in
1083 * the chain. This has implications for ownership, since non-head nodes are
1084 * owned by the chain head. You are then responsible for relinquishing
1085 * ownership of the moved-to node, and manually deleting the moved-from
1088 * With the move assignment operator, the destination of the move should be
1089 * the head of an IOBuf chain or a solitary IOBuf not part of a chain. If
1090 * the move destination is part of a chain, all other IOBufs in the chain
1093 * (We currently don't provide a copy constructor or assignment operator.
1094 * The main reason is because it is not clear these operations should copy
1095 * the entire chain or just the single IOBuf.)
1097 IOBuf(IOBuf&& other) noexcept;
1098 IOBuf& operator=(IOBuf&& other) noexcept;
1101 enum FlagsEnum : uint32_t {
1102 kFlagUserOwned = 0x1,
1103 kFlagFreeSharedInfo = 0x2,
1104 kFlagMaybeShared = 0x4,
1107 // Values for the type_ field.
1108 // We currently don't really use this for anything, other than to have it
1109 // around for debugging purposes. We store it at the moment just because we
1110 // have the 4 extra bytes that would just be padding otherwise.
1111 enum ExtBufTypeEnum {
1113 kExtUserSupplied = 1,
1120 SharedInfo(FreeFunction fn, void* arg);
1122 // A pointer to a function to call to free the buffer when the refcount
1123 // hits 0. If this is null, free() will be used instead.
1124 FreeFunction freeFn;
1126 std::atomic<uint32_t> refcount;
1128 // Helper structs for use by operator new and delete
1131 struct HeapFullStorage;
1133 // Forbidden copy constructor and assignment opererator
1134 IOBuf(IOBuf const &);
1135 IOBuf& operator=(IOBuf const &);
1138 * Create a new IOBuf pointing to an external buffer.
1140 * The caller is responsible for holding a reference count for this new
1141 * IOBuf. The IOBuf constructor does not automatically increment the
1144 IOBuf(ExtBufTypeEnum type, uint32_t flags,
1145 uint8_t* buf, uint32_t capacity,
1146 uint8_t* data, uint32_t length,
1147 SharedInfo* sharedInfo);
1149 void unshareOneSlow();
1150 void unshareChained();
1151 void coalesceSlow();
1152 void coalesceSlow(size_t maxLength);
1153 // newLength must be the entire length of the buffers between this and
1154 // end (no truncation)
1155 void coalesceAndReallocate(
1159 size_t newTailroom);
1160 void coalesceAndReallocate(size_t newLength, IOBuf* end) {
1161 coalesceAndReallocate(headroom(), newLength, end, end->prev_->tailroom());
1163 void decrementRefcount();
1164 void reserveSlow(uint32_t minHeadroom, uint32_t minTailroom);
1165 void freeExtBuffer();
1167 static size_t goodExtBufferSize(uint32_t minCapacity);
1168 static void initExtBuffer(uint8_t* buf, size_t mallocSize,
1169 SharedInfo** infoReturn,
1170 uint32_t* capacityReturn);
1171 static void allocExtBuffer(uint32_t minCapacity,
1172 uint8_t** bufReturn,
1173 SharedInfo** infoReturn,
1174 uint32_t* capacityReturn);
1175 static void releaseStorage(HeapStorage* storage, uint16_t freeFlags);
1176 static void freeInternalBuf(void* buf, void* userData);
1183 * Links to the next and the previous IOBuf in this chain.
1185 * The chain is circularly linked (the last element in the chain points back
1186 * at the head), and next_ and prev_ can never be null. If this IOBuf is the
1187 * only element in the chain, next_ and prev_ will both point to this.
1193 * A pointer to the start of the data referenced by this IOBuf, and the
1194 * length of the data.
1196 * This may refer to any subsection of the actual buffer capacity.
1198 uint8_t* data_{nullptr};
1199 uint8_t* buf_{nullptr};
1200 uint32_t length_{0};
1201 uint32_t capacity_{0};
1202 mutable uint32_t flags_{kFlagUserOwned};
1203 uint32_t type_{kExtUserOwned};
1204 // SharedInfo may be NULL if kFlagUserOwned is set. It is non-NULL
1205 // in all other cases.
1206 SharedInfo* sharedInfo_{nullptr};
1208 struct DeleterBase {
1209 virtual ~DeleterBase() { }
1210 virtual void dispose(void* p) = 0;
1213 template <class UniquePtr>
1214 struct UniquePtrDeleter : public DeleterBase {
1215 typedef typename UniquePtr::pointer Pointer;
1216 typedef typename UniquePtr::deleter_type Deleter;
1218 explicit UniquePtrDeleter(Deleter deleter) : deleter_(std::move(deleter)){ }
1219 void dispose(void* p) {
1221 deleter_(static_cast<Pointer>(p));
1232 static void freeUniquePtrBuffer(void* ptr, void* userData) {
1233 static_cast<DeleterBase*>(userData)->dispose(ptr);
1237 template <class UniquePtr>
1238 typename std::enable_if<detail::IsUniquePtrToSL<UniquePtr>::value,
1239 std::unique_ptr<IOBuf>>::type
1240 IOBuf::takeOwnership(UniquePtr&& buf, size_t count) {
1241 size_t size = count * sizeof(typename UniquePtr::element_type);
1242 DCHECK_LT(size, size_t(std::numeric_limits<uint32_t>::max()));
1243 auto deleter = new UniquePtrDeleter<UniquePtr>(buf.get_deleter());
1244 return takeOwnership(buf.release(),
1246 &IOBuf::freeUniquePtrBuffer,
1250 inline std::unique_ptr<IOBuf> IOBuf::copyBuffer(
1251 const void* data, uint32_t size, uint32_t headroom,
1252 uint32_t minTailroom) {
1253 uint32_t capacity = headroom + size + minTailroom;
1254 std::unique_ptr<IOBuf> buf = create(capacity);
1255 buf->advance(headroom);
1256 memcpy(buf->writableData(), data, size);
1261 inline std::unique_ptr<IOBuf> IOBuf::copyBuffer(const std::string& buf,
1263 uint32_t minTailroom) {
1264 return copyBuffer(buf.data(), buf.size(), headroom, minTailroom);
1267 inline std::unique_ptr<IOBuf> IOBuf::maybeCopyBuffer(const std::string& buf,
1269 uint32_t minTailroom) {
1273 return copyBuffer(buf.data(), buf.size(), headroom, minTailroom);
1276 class IOBuf::Iterator : public boost::iterator_facade<
1277 IOBuf::Iterator, // Derived
1278 const ByteRange, // Value
1279 boost::forward_traversal_tag // Category or traversal
1281 friend class boost::iterator_core_access;
1283 // Note that IOBufs are stored as a circular list without a guard node,
1284 // so pos == end is ambiguous (it may mean "begin" or "end"). To solve
1285 // the ambiguity (at the cost of one extra comparison in the "increment"
1286 // code path), we define end iterators as having pos_ == end_ == nullptr
1287 // and we only allow forward iteration.
1288 explicit Iterator(const IOBuf* pos, const IOBuf* end)
1291 // Sadly, we must return by const reference, not by value.
1299 val_ = ByteRange(pos_->data(), pos_->tail());
1302 void adjustForEnd() {
1304 pos_ = end_ = nullptr;
1311 const ByteRange& dereference() const {
1315 bool equal(const Iterator& other) const {
1316 // We must compare end_ in addition to pos_, because forward traversal
1317 // requires that if two iterators are equal (a == b) and dereferenceable,
1319 return pos_ == other.pos_ && end_ == other.end_;
1323 pos_ = pos_->next();
1332 inline IOBuf::Iterator IOBuf::begin() const { return cbegin(); }
1333 inline IOBuf::Iterator IOBuf::end() const { return cend(); }
1337 #pragma GCC diagnostic pop
1339 #endif // FOLLY_IO_IOBUF_H_