2 * Copyright 2012 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>
32 * An IOBuf is a pointer to a buffer of data.
34 * IOBuf objects are intended to be used primarily for networking code, and are
35 * modelled somewhat after FreeBSD's mbuf data structure, and Linux's sk_buff
38 * IOBuf objects facilitate zero-copy network programming, by allowing multiple
39 * IOBuf objects to point to the same underlying buffer of data, using a
40 * reference count to track when the buffer is no longer needed and can be
47 * The IOBuf itself is a small object containing a pointer to the buffer and
48 * information about which segment of the buffer contains valid data.
50 * The data layout looks like this:
58 * +------------+--------------------+-----------+
59 * | headroom | data | tailroom |
60 * +------------+--------------------+-----------+
62 * buffer() data() tail() bufferEnd()
64 * The length() method returns the length of the valid data; capacity()
65 * returns the entire capacity of the buffer (from buffer() to bufferEnd()).
66 * The headroom() and tailroom() methods return the amount of unused capacity
67 * available before and after the data.
73 * The buffer itself is reference counted, and multiple IOBuf objects may point
74 * to the same buffer. Each IOBuf may point to a different section of valid
75 * data within the underlying buffer. For example, if multiple protocol
76 * requests are read from the network into a single buffer, a separate IOBuf
77 * may be created for each request, all sharing the same underlying buffer.
79 * In other words, when multiple IOBufs share the same underlying buffer, the
80 * data() and tail() methods on each IOBuf may point to a different segment of
81 * the data. However, the buffer() and bufferEnd() methods will point to the
82 * same location for all IOBufs sharing the same underlying buffer.
84 * +-----------+ +---------+
85 * | IOBuf 1 | | IOBuf 2 |
86 * +-----------+ +---------+
88 * data | tail |/ data | tail
90 * +-------------------------------------+
92 * +-------------------------------------+
94 * If you only read data from an IOBuf, you don't need to worry about other
95 * IOBuf objects possibly sharing the same underlying buffer. However, if you
96 * ever write to the buffer you need to first ensure that no other IOBufs point
97 * to the same buffer. The unshare() method may be used to ensure that you
98 * have an unshared buffer.
104 * IOBuf objects also contain pointers to next and previous IOBuf objects.
105 * This can be used to represent a single logical piece of data that its stored
106 * in non-contiguous chunks in separate buffers.
108 * A single IOBuf object can only belong to one chain at a time.
110 * IOBuf chains are always circular. The "prev" pointer in the head of the
111 * chain points to the tail of the chain. However, it is up to the user to
112 * decide which IOBuf is the head. Internally the IOBuf code does not care
113 * which element is the head.
115 * The lifetime of all IOBufs in the chain are linked: when one element in the
116 * chain is deleted, all other chained elements are also deleted. Conceptually
117 * it is simplest to treat this as if the head of the chain owns all other
118 * IOBufs in the chain. When you delete the head of the chain, it will delete
119 * the other elements as well. For this reason, prependChain() and
120 * appendChain() take ownership of of the new elements being added to this
123 * When the coalesce() method is used to coalesce an entire IOBuf chain into a
124 * single IOBuf, all other IOBufs in the chain are eliminated and automatically
125 * deleted. The unshare() method may coalesce the chain; if it does it will
126 * similarly delete all IOBufs eliminated from the chain.
128 * As discussed in the following section, it is up to the user to maintain a
129 * lock around the entire IOBuf chain if multiple threads need to access the
130 * chain. IOBuf does not provide any internal locking.
136 * When used in multithread programs, a single IOBuf object should only be used
137 * in a single thread at a time. If a caller uses a single IOBuf across
138 * multiple threads the caller is responsible for using an external lock to
139 * synchronize access to the IOBuf.
141 * Two separate IOBuf objects may be accessed concurrently in separate threads
142 * without locking, even if they point to the same underlying buffer. The
143 * buffer reference count is always accessed atomically, and no other
144 * operations should affect other IOBufs that point to the same data segment.
145 * The caller is responsible for using unshare() to ensure that the data buffer
146 * is not shared by other IOBufs before writing to it, and this ensures that
147 * the data itself is not modified in one thread while also being accessed from
150 * For IOBuf chains, no two IOBufs in the same chain should be accessed
151 * simultaneously in separate threads. The caller must maintain a lock around
152 * the entire chain if the chain, or individual IOBufs in the chain, may be
153 * accessed by multiple threads.
156 * IOBuf Object Allocation/Sharing
157 * -------------------------------
159 * IOBuf objects themselves are always allocated on the heap. The IOBuf
160 * constructors are private, so IOBuf objects may not be created on the stack.
161 * In part this is done since some IOBuf objects use small-buffer optimization
162 * and contain the buffer data immediately after the IOBuf object itself. The
163 * coalesce() and unshare() methods also expect to be able to delete subsequent
164 * IOBuf objects in the chain if they are no longer needed due to coalescing.
166 * The IOBuf structure also does not provide room for an intrusive refcount on
167 * the IOBuf object itself, only the underlying data buffer is reference
168 * counted. If users want to share the same IOBuf object between multiple
169 * parts of the code, they are responsible for managing this sharing on their
170 * own. (For example, by using a shared_ptr. Alternatively, users always have
171 * the option of using clone() to create a second IOBuf that points to the same
172 * underlying buffer.)
174 * With jemalloc, allocating small objects like IOBuf objects should be
175 * relatively fast, and the cost of allocating IOBuf objects on the heap and
176 * cloning new IOBufs should be relatively cheap.
180 typedef void (*FreeFunction)(void* buf, void* userData);
183 * Allocate a new IOBuf object with the requested capacity.
185 * Returns a new IOBuf object that must be (eventually) deleted by the
186 * caller. The returned IOBuf may actually have slightly more capacity than
189 * The data pointer will initially point to the start of the newly allocated
190 * buffer, and will have a data length of 0.
192 * Throws std::bad_alloc on error.
194 static std::unique_ptr<IOBuf> create(uint32_t capacity);
197 * Create a new IOBuf pointing to an existing data buffer.
199 * The new IOBuffer will assume ownership of the buffer, and free it by
200 * calling the specified FreeFunction when the last IOBuf pointing to this
201 * buffer is destroyed. The function will be called with a pointer to the
202 * buffer as the first argument, and the supplied userData value as the
203 * second argument. The free function must never throw exceptions.
205 * If no FreeFunction is specified, the buffer will be freed using free().
207 * The IOBuf data pointer will initially point to the start of the buffer,
208 * and the length will be the full capacity of the buffer.
210 * On error, std::bad_alloc will be thrown. If freeOnError is true (the
211 * default) the buffer will be freed before throwing the error.
213 static std::unique_ptr<IOBuf> takeOwnership(void* buf, uint32_t capacity,
214 FreeFunction freeFn = NULL,
215 void* userData = NULL,
216 bool freeOnError = true);
219 * Create a new IOBuf object that points to an existing user-owned buffer.
221 * This should only be used when the caller knows the lifetime of the IOBuf
222 * object ahead of time and can ensure that all IOBuf objects that will point
223 * to this buffer will be destroyed before the buffer itself is destroyed.
225 * This buffer will not be freed automatically when the last IOBuf
226 * referencing it is destroyed. It is the caller's responsibility to free
227 * the buffer after the last IOBuf has been destroyed.
229 * The IOBuf data pointer will initially point to the start of the buffer,
230 * and the length will be the full capacity of the buffer.
232 * An IOBuf created using wrapBuffer() will always be reported as shared.
233 * unshare() may be used to create a writable copy of the buffer.
235 * On error, std::bad_alloc will be thrown.
237 static std::unique_ptr<IOBuf> wrapBuffer(const void* buf, uint32_t capacity);
240 * Convenience function to create a new IOBuf object that copies data from a
241 * user-supplied buffer, optionally allocating a given amount of
242 * headroom and tailroom.
244 static std::unique_ptr<IOBuf> copyBuffer(const void* buf, uint32_t size,
246 uint32_t minTailroom=0);
249 * Convenience function to free a chain of IOBufs held by a unique_ptr.
251 static void destroy(std::unique_ptr<IOBuf>&& data) {
252 auto destroyer = std::move(data);
256 * Destroy this IOBuf.
258 * Deleting an IOBuf will automatically destroy all IOBufs in the chain.
259 * (See the comments above regarding the ownership model of IOBuf chains.
260 * All subsequent IOBufs in the chain are considered to be owned by the head
261 * of the chain. Users should only explicitly delete the head of a chain.)
263 * When each individual IOBuf is destroyed, it will release its reference
264 * count on the underlying buffer. If it was the last user of the buffer,
265 * the buffer will be freed.
270 * Check whether the chain is empty (i.e., whether the IOBufs in the
271 * chain have a total data length of zero).
273 * This method is semantically equivalent to
274 * i->computeChainDataLength()==0
275 * but may run faster because it can short-circuit as soon as it
276 * encounters a buffer with length()!=0
281 * Get the pointer to the start of the data.
283 const uint8_t* data() const {
288 * Get a writable pointer to the start of the data.
290 * The caller is responsible for calling unshare() first to ensure that it is
291 * actually safe to write to the buffer.
293 uint8_t* writableData() {
298 * Get the pointer to the end of the data.
300 const uint8_t* tail() const {
301 return data_ + length_;
305 * Get a writable pointer to the end of the data.
307 * The caller is responsible for calling unshare() first to ensure that it is
308 * actually safe to write to the buffer.
310 uint8_t* writableTail() {
311 return data_ + length_;
315 * Get the data length.
317 uint32_t length() const {
322 * Get the amount of head room.
324 * Returns the number of bytes in the buffer before the start of the data.
326 uint32_t headroom() const {
327 return data_ - buffer();
331 * Get the amount of tail room.
333 * Returns the number of bytes in the buffer after the end of the data.
335 uint32_t tailroom() const {
336 return bufferEnd() - tail();
340 * Get the pointer to the start of the buffer.
342 * Note that this is the pointer to the very beginning of the usable buffer,
343 * not the start of valid data within the buffer. Use the data() method to
344 * get a pointer to the start of the data within the buffer.
346 const uint8_t* buffer() const {
347 return (flags_ & kFlagExt) ? ext_.buf : int_.buf;
351 * Get a writable pointer to the start of the buffer.
353 * The caller is responsible for calling unshare() first to ensure that it is
354 * actually safe to write to the buffer.
356 uint8_t* writableBuffer() {
357 return (flags_ & kFlagExt) ? ext_.buf : int_.buf;
361 * Get the pointer to the end of the buffer.
363 * Note that this is the pointer to the very end of the usable buffer,
364 * not the end of valid data within the buffer. Use the tail() method to
365 * get a pointer to the end of the data within the buffer.
367 const uint8_t* bufferEnd() const {
368 return (flags_ & kFlagExt) ?
369 ext_.buf + ext_.capacity :
370 int_.buf + int_.capacity;
374 * Get the total size of the buffer.
376 * This returns the total usable length of the buffer. Use the length()
377 * method to get the length of the actual valid data in this IOBuf.
379 uint32_t capacity() const {
380 return (flags_ & kFlagExt) ? ext_.capacity : int_.capacity;
384 * Get a pointer to the next IOBuf in this chain.
389 const IOBuf* next() const {
394 * Get a pointer to the previous IOBuf in this chain.
399 const IOBuf* prev() const {
404 * Shift the data forwards in the buffer.
406 * This shifts the data pointer forwards in the buffer to increase the
407 * headroom. This is commonly used to increase the headroom in a newly
410 * The caller is responsible for ensuring that there is sufficient
411 * tailroom in the buffer before calling advance().
413 * If there is a non-zero data length, advance() will use memmove() to shift
414 * the data forwards in the buffer. In this case, the caller is responsible
415 * for making sure the buffer is unshared, so it will not affect other IOBufs
416 * that may be sharing the same underlying buffer.
418 void advance(uint32_t amount) {
419 // In debug builds, assert if there is a problem.
420 assert(amount <= tailroom());
423 memmove(data_ + amount, data_, length_);
429 * Shift the data backwards in the buffer.
431 * The caller is responsible for ensuring that there is sufficient headroom
432 * in the buffer before calling retreat().
434 * If there is a non-zero data length, retreat() will use memmove() to shift
435 * the data backwards in the buffer. In this case, the caller is responsible
436 * for making sure the buffer is unshared, so it will not affect other IOBufs
437 * that may be sharing the same underlying buffer.
439 void retreat(uint32_t amount) {
440 // In debug builds, assert if there is a problem.
441 assert(amount <= headroom());
444 memmove(data_ - amount, data_, length_);
450 * Adjust the data pointer to include more valid data at the beginning.
452 * This moves the data pointer backwards to include more of the available
453 * buffer. The caller is responsible for ensuring that there is sufficient
454 * headroom for the new data. The caller is also responsible for populating
455 * this section with valid data.
457 * This does not modify any actual data in the buffer.
459 void prepend(uint32_t amount) {
460 CHECK(amount <= headroom());
465 * Adjust the tail pointer to include more valid data at the end.
467 * This moves the tail pointer forwards to include more of the available
468 * buffer. The caller is responsible for ensuring that there is sufficient
469 * tailroom for the new data. The caller is also responsible for populating
470 * this section with valid data.
472 * This does not modify any actual data in the buffer.
474 void append(uint32_t amount) {
475 CHECK(amount <= tailroom());
480 * Adjust the data pointer forwards to include less valid data.
482 * This moves the data pointer forwards so that the first amount bytes are no
483 * longer considered valid data. The caller is responsible for ensuring that
484 * amount is less than or equal to the actual data length.
486 * This does not modify any actual data in the buffer.
488 void trimStart(uint32_t amount) {
489 CHECK(amount <= length_);
495 * Adjust the tail pointer backwards to include less valid data.
497 * This moves the tail pointer backwards so that the last amount bytes are no
498 * longer considered valid data. The caller is responsible for ensuring that
499 * amount is less than or equal to the actual data length.
501 * This does not modify any actual data in the buffer.
503 void trimEnd(uint32_t amount) {
504 CHECK(amount <= length_);
511 * Postcondition: headroom() == 0, length() == 0, tailroom() == capacity()
514 data_ = writableBuffer();
519 * Ensure that this buffer has at least minHeadroom headroom bytes and at
520 * least minTailroom tailroom bytes. The buffer must be writable
521 * (you must call unshare() before this, if necessary).
523 * Postcondition: headroom() >= minHeadroom, tailroom() >= minTailroom,
524 * the data (between data() and data() + length()) is preserved.
526 void reserve(uint32_t minHeadroom, uint32_t minTailroom) {
527 // Maybe we don't need to do anything.
528 if (headroom() >= minHeadroom && tailroom() >= minTailroom) {
531 // If the buffer is empty but we have enough total room (head + tail),
532 // move the data_ pointer around.
534 headroom() + tailroom() >= minHeadroom + minTailroom) {
535 data_ = writableBuffer() + minHeadroom;
538 // Bah, we have to do actual work.
539 reserveSlow(minHeadroom, minTailroom);
543 * Return true if this IOBuf is part of a chain of multiple IOBufs, or false
544 * if this is the only IOBuf in its chain.
546 bool isChained() const {
547 assert((next_ == this) == (prev_ == this));
548 return next_ != this;
552 * Get the number of IOBufs in this chain.
554 * Beware that this method has to walk the entire chain.
555 * Use isChained() if you just want to check if this IOBuf is part of a chain
558 uint32_t countChainElements() const;
561 * Get the length of all the data in this IOBuf chain.
563 * Beware that this method has to walk the entire chain.
565 uint64_t computeChainDataLength() const;
568 * Insert another IOBuf chain immediately before this IOBuf.
570 * For example, if there are two IOBuf chains (A, B, C) and (D, E, F),
571 * and B->prependChain(D) is called, the (D, E, F) chain will be subsumed
572 * and become part of the chain starting at A, which will now look like
575 * Note that since IOBuf chains are circular, head->prependChain(other) can
576 * be used to append the other chain at the very end of the chain pointed to
577 * by head. For example, if there are two IOBuf chains (A, B, C) and
578 * (D, E, F), and A->prependChain(D) is called, the chain starting at A will
579 * now consist of (A, B, C, D, E, F)
581 * The elements in the specified IOBuf chain will become part of this chain,
582 * and will be owned by the head of this chain. When this chain is
583 * destroyed, all elements in the supplied chain will also be destroyed.
585 * For this reason, appendChain() only accepts an rvalue-reference to a
586 * unique_ptr(), to make it clear that it is taking ownership of the supplied
587 * chain. If you have a raw pointer, you can pass in a new temporary
588 * unique_ptr around the raw pointer. If you have an existing,
589 * non-temporary unique_ptr, you must call std::move(ptr) to make it clear
590 * that you are destroying the original pointer.
592 void prependChain(std::unique_ptr<IOBuf>&& iobuf);
595 * Append another IOBuf chain immediately after this IOBuf.
597 * For example, if there are two IOBuf chains (A, B, C) and (D, E, F),
598 * and B->appendChain(D) is called, the (D, E, F) chain will be subsumed
599 * and become part of the chain starting at A, which will now look like
602 * The elements in the specified IOBuf chain will become part of this chain,
603 * and will be owned by the head of this chain. When this chain is
604 * destroyed, all elements in the supplied chain will also be destroyed.
606 * For this reason, appendChain() only accepts an rvalue-reference to a
607 * unique_ptr(), to make it clear that it is taking ownership of the supplied
608 * chain. If you have a raw pointer, you can pass in a new temporary
609 * unique_ptr around the raw pointer. If you have an existing,
610 * non-temporary unique_ptr, you must call std::move(ptr) to make it clear
611 * that you are destroying the original pointer.
613 void appendChain(std::unique_ptr<IOBuf>&& iobuf) {
614 // Just use prependChain() on the next element in our chain
615 next_->prependChain(std::move(iobuf));
619 * Remove this IOBuf from its current chain.
621 * Since ownership of all elements an IOBuf chain is normally maintained by
622 * the head of the chain, unlink() transfers ownership of this IOBuf from the
623 * chain and gives it to the caller. A new unique_ptr to the IOBuf is
624 * returned to the caller. The caller must store the returned unique_ptr (or
625 * call release() on it) to take ownership, otherwise the IOBuf will be
626 * immediately destroyed.
628 * Since unlink transfers ownership of the IOBuf to the caller, be careful
629 * not to call unlink() on the head of a chain if you already maintain
630 * ownership on the head of the chain via other means. The pop() method
631 * is a better choice for that situation.
633 std::unique_ptr<IOBuf> unlink() {
634 next_->prev_ = prev_;
635 prev_->next_ = next_;
638 return std::unique_ptr<IOBuf>(this);
642 * Remove this IOBuf from its current chain and return a unique_ptr to
643 * the IOBuf that formerly followed it in the chain.
645 std::unique_ptr<IOBuf> pop() {
647 next_->prev_ = prev_;
648 prev_->next_ = next_;
651 return std::unique_ptr<IOBuf>((next == this) ? NULL : next);
655 * Remove a subchain from this chain.
657 * Remove the subchain starting at head and ending at tail from this chain.
659 * Returns a unique_ptr pointing to head. (In other words, ownership of the
660 * head of the subchain is transferred to the caller.) If the caller ignores
661 * the return value and lets the unique_ptr be destroyed, the subchain will
662 * be immediately destroyed.
664 * The subchain referenced by the specified head and tail must be part of the
665 * same chain as the current IOBuf, but must not contain the current IOBuf.
666 * However, the specified head and tail may be equal to each other (i.e.,
667 * they may be a subchain of length 1).
669 std::unique_ptr<IOBuf> separateChain(IOBuf* head, IOBuf* tail) {
670 assert(head != this);
671 assert(tail != this);
673 head->prev_->next_ = tail->next_;
674 tail->next_->prev_ = head->prev_;
679 return std::unique_ptr<IOBuf>(head);
683 * Return true if at least one of the IOBufs in this chain are shared,
684 * or false if all of the IOBufs point to unique buffers.
686 * Use isSharedOne() to only check this IOBuf rather than the entire chain.
688 bool isShared() const {
689 const IOBuf* current = this;
691 if (current->isSharedOne()) {
694 current = current->next_;
695 if (current == this) {
702 * Return true if other IOBufs are also pointing to the buffer used by this
703 * IOBuf, and false otherwise.
705 * If this IOBuf points at a buffer owned by another (non-IOBuf) part of the
706 * code (i.e., if the IOBuf was created using wrapBuffer(), or was cloned
707 * from such an IOBuf), it is always considered shared.
709 * This only checks the current IOBuf, and not other IOBufs in the chain.
711 bool isSharedOne() const {
712 // If this is a user-owned buffer, it is always considered shared
713 if (flags_ & kFlagUserOwned) {
717 if (flags_ & kFlagExt) {
718 return ext_.sharedInfo->refcount.load(std::memory_order_acquire) > 1;
725 * Ensure that this IOBuf has a unique buffer that is not shared by other
728 * unshare() operates on an entire chain of IOBuf objects. If the chain is
729 * shared, it may also coalesce the chain when making it unique. If the
730 * chain is coalesced, subsequent IOBuf objects in the current chain will be
731 * automatically deleted.
733 * Note that buffers owned by other (non-IOBuf) users are automatically
736 * Throws std::bad_alloc on error. On error the IOBuf chain will be
739 * Currently unshare may also throw std::overflow_error if it tries to
740 * coalesce. (TODO: In the future it would be nice if unshare() were smart
741 * enough not to coalesce the entire buffer if the data is too large.
742 * However, in practice this seems unlikely to become an issue.)
753 * Ensure that this IOBuf has a unique buffer that is not shared by other
756 * unshareOne() operates on a single IOBuf object. This IOBuf will have a
757 * unique buffer after unshareOne() returns, but other IOBufs in the chain
758 * may still be shared after unshareOne() returns.
760 * Throws std::bad_alloc on error. On error the IOBuf will be unmodified.
769 * Coalesce this IOBuf chain into a single buffer.
771 * This method moves all of the data in this IOBuf chain into a single
772 * contiguous buffer, if it is not already in one buffer. After coalesce()
773 * returns, this IOBuf will be a chain of length one. Other IOBufs in the
774 * chain will be automatically deleted.
776 * After coalescing, the IOBuf will have at least as much headroom as the
777 * first IOBuf in the chain, and at least as much tailroom as the last IOBuf
780 * Throws std::bad_alloc on error. On error the IOBuf chain will be
781 * unmodified. Throws std::overflow_error if the length of the entire chain
782 * larger than can be described by a uint32_t capacity.
792 * Ensure that this chain has at least maxLength bytes available as a
793 * contiguous memory range.
795 * This method coalesces whole buffers in the chain into this buffer as
796 * necessary until this buffer's length() is at least maxLength.
798 * After coalescing, the IOBuf will have at least as much headroom as the
799 * first IOBuf in the chain, and at least as much tailroom as the last IOBuf
800 * that was coalesced.
802 * Throws std::bad_alloc on error. On error the IOBuf chain will be
803 * unmodified. Throws std::overflow_error if the length of the coalesced
804 * portion of the chain is larger than can be described by a uint32_t
805 * capacity. (Although maxLength is uint32_t, gather() doesn't split
806 * buffers, so coalescing whole buffers may result in a capacity that can't
807 * be described in uint32_t.
809 * Upon return, either enough of the chain was coalesced into a contiguous
810 * region, or the entire chain was coalesced. That is,
811 * length() >= maxLength || !isChained() is true.
813 void gather(uint32_t maxLength) {
814 if (!isChained() || length_ >= maxLength) {
817 coalesceSlow(maxLength);
821 * Return a new IOBuf chain sharing the same data as this chain.
823 * The new IOBuf chain will normally point to the same underlying data
824 * buffers as the original chain. (The one exception to this is if some of
825 * the IOBufs in this chain contain small internal data buffers which cannot
828 std::unique_ptr<IOBuf> clone() const;
831 * Return a new IOBuf with the same data as this IOBuf.
833 * The new IOBuf returned will not be part of a chain (even if this IOBuf is
834 * part of a larger chain).
836 std::unique_ptr<IOBuf> cloneOne() const;
838 // Overridden operator new and delete.
839 // These directly use malloc() and free() to allocate the space for IOBuf
840 // objects. This is needed since IOBuf::create() manually uses malloc when
841 // allocating IOBuf objects with an internal buffer.
842 void* operator new(size_t size);
843 void* operator new(size_t size, void* ptr);
844 void operator delete(void* ptr);
849 kFlagUserOwned = 0x2,
850 kFlagFreeSharedInfo = 0x4,
853 // Values for the ExternalBuf type field.
854 // We currently don't really use this for anything, other than to have it
855 // around for debugging purposes. We store it at the moment just because we
856 // have the 4 extra bytes in the ExternalBuf struct that would just be
857 // padding otherwise.
858 enum ExtBufTypeEnum {
860 kExtUserSupplied = 1,
866 SharedInfo(FreeFunction fn, void* arg);
868 // A pointer to a function to call to free the buffer when the refcount
869 // hits 0. If this is NULL, free() will be used instead.
872 std::atomic<uint32_t> refcount;
878 // SharedInfo may be NULL if kFlagUserOwned is set. It is non-NULL
879 // in all other cases.
880 SharedInfo* sharedInfo;
887 // The maximum size for an IOBuf object, including any internal data buffer
888 static const uint32_t kMaxIOBufSize = 256;
889 static const uint32_t kMaxInternalDataSize;
891 // Forbidden copy constructor and assignment opererator
892 IOBuf(IOBuf const &);
893 IOBuf& operator=(IOBuf const &);
896 * Create a new IOBuf with internal data.
898 * end is a pointer to the end of the IOBuf's internal data buffer.
900 explicit IOBuf(uint8_t* end);
903 * Create a new IOBuf pointing to an external buffer.
905 * The caller is responsible for holding a reference count for this new
906 * IOBuf. The IOBuf constructor does not automatically increment the
909 IOBuf(ExtBufTypeEnum type, uint32_t flags,
910 uint8_t* buf, uint32_t capacity,
911 uint8_t* data, uint32_t length,
912 SharedInfo* sharedInfo);
914 void unshareOneSlow();
915 void unshareChained();
916 void coalesceSlow(size_t maxLength=std::numeric_limits<size_t>::max());
917 void decrementRefcount();
918 void reserveSlow(uint32_t minHeadroom, uint32_t minTailroom);
920 static size_t goodExtBufferSize(uint32_t minCapacity);
921 static void initExtBuffer(uint8_t* buf, size_t mallocSize,
922 SharedInfo** infoReturn,
923 uint32_t* capacityReturn);
924 static void allocExtBuffer(uint32_t minCapacity,
926 SharedInfo** infoReturn,
927 uint32_t* capacityReturn);
934 * Links to the next and the previous IOBuf in this chain.
936 * The chain is circularly linked (the last element in the chain points back
937 * at the head), and next_ and prev_ can never be NULL. If this IOBuf is the
938 * only element in the chain, next_ and prev_ will both point to this.
944 * A pointer to the start of the data referenced by this IOBuf, and the
945 * length of the data.
947 * This may refer to any subsection of the actual buffer capacity.
959 inline std::unique_ptr<IOBuf> IOBuf::copyBuffer(
960 const void* data, uint32_t size, uint32_t headroom,
961 uint32_t minTailroom) {
962 uint32_t capacity = headroom + size + minTailroom;
963 std::unique_ptr<IOBuf> buf = create(capacity);
964 buf->advance(headroom);
965 memcpy(buf->writableData(), data, size);
972 #endif // FOLLY_IO_IOBUF_H_