2 * Copyright 2013 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_QUEUE_H
18 #define FOLLY_IO_IOBUF_QUEUE_H
20 #include "folly/io/IOBuf.h"
28 * An IOBufQueue encapsulates a chain of IOBufs and provides
29 * convenience functions to append data to the back of the chain
30 * and remove data from the front.
32 * You may also prepend data into the headroom of the first buffer in the
38 Options() : cacheChainLength(false) { }
39 bool cacheChainLength;
43 * Commonly used Options, currently the only possible value other than
46 static Options cacheChainLength() {
48 options.cacheChainLength = true;
52 explicit IOBufQueue(const Options& options = Options());
55 * Return a space to prepend bytes and the amount of headroom available.
57 std::pair<void*, uint32_t> headroom();
60 * Indicate that n bytes from the headroom have been used.
62 void markPrepended(uint32_t n);
65 * Prepend an existing range; throws std::overflow_error if not enough
68 void prepend(const void* buf, uint32_t n);
71 * Add a buffer or buffer chain to the end of this queue. The
72 * queue takes ownership of buf.
74 void append(std::unique_ptr<folly::IOBuf>&& buf);
77 * Add a queue to the end of this queue. The queue takes ownership of
78 * all buffers from the other queue.
80 void append(IOBufQueue& other);
81 void append(IOBufQueue&& other) {
82 append(other); // call lvalue reference overload, above
86 * Copy len bytes, starting at buf, to the end of this queue.
87 * The caller retains ownership of the source data.
89 void append(const void* buf, size_t len);
92 * Copy a string to the end of this queue.
93 * The caller retains ownership of the source data.
95 void append(const std::string& buf) {
96 append(buf.data(), buf.length());
100 * Append a chain of IOBuf objects that point to consecutive regions
103 * Just like IOBuf::wrapBuffer, this should only be used when the caller
104 * knows ahead of time and can ensure that all IOBuf objects that will point
105 * to this buffer will be destroyed before the buffer itself is destroyed;
106 * all other caveats from wrapBuffer also apply.
108 * Every buffer except for the last will wrap exactly blockSize bytes.
109 * Importantly, this method may be used to wrap buffers larger than 4GB.
111 void wrapBuffer(const void* buf, size_t len,
112 uint32_t blockSize=(1U << 31)); // default block size: 2GB
115 * Obtain a writable block of contiguous bytes at the end of this
116 * queue, allocating more space if necessary. The amount of space
117 * reserved will be at least min. If min contiguous space is not
118 * available at the end of the queue, and IOBuf with size newAllocationSize
119 * is appended to the chain and returned. The actual available space
120 * may be larger than newAllocationSize, but will be truncated to max,
123 * If the caller subsequently writes anything into the returned space,
124 * it must call the postallocate() method.
126 * @return The starting address of the block and the length in bytes.
128 * @note The point of the preallocate()/postallocate() mechanism is
129 * to support I/O APIs such as Thrift's TAsyncSocket::ReadCallback
130 * that request a buffer from the application and then, in a later
131 * callback, tell the application how much of the buffer they've
134 std::pair<void*,uint32_t> preallocate(
135 uint32_t min, uint32_t newAllocationSize,
136 uint32_t max = std::numeric_limits<uint32_t>::max());
139 * Tell the queue that the caller has written data into the first n
140 * bytes provided by the previous preallocate() call.
142 * @note n should be less than or equal to the size returned by
143 * preallocate(). If n is zero, the caller may skip the call
144 * to postallocate(). If n is nonzero, the caller must not
145 * invoke any other non-const methods on this IOBufQueue between
146 * the call to preallocate and the call to postallocate().
148 void postallocate(uint32_t n);
151 * Obtain a writable block of n contiguous bytes, allocating more space
152 * if necessary, and mark it as used. The caller can fill it later.
154 void* allocate(uint32_t n) {
155 void* p = preallocate(n, n).first;
161 * Split off the first n bytes of the queue into a separate IOBuf chain,
162 * and transfer ownership of the new chain to the caller. The IOBufQueue
163 * retains ownership of everything after the split point.
165 * @warning If the split point lies in the middle of some IOBuf within
166 * the chain, this function may, as an implementation detail,
169 * @throws std::underflow_error if n exceeds the number of bytes
172 std::unique_ptr<folly::IOBuf> split(size_t n);
175 * Similar to IOBuf::trimStart, but works on the whole queue. Will
176 * pop off buffers that have been completely trimmed.
178 void trimStart(size_t amount);
181 * Similar to IOBuf::trimEnd, but works on the whole queue. Will
182 * pop off buffers that have been completely trimmed.
184 void trimEnd(size_t amount);
187 * Transfer ownership of the queue's entire IOBuf chain to the caller.
189 std::unique_ptr<folly::IOBuf> move() {
191 return std::move(head_);
197 const folly::IOBuf* front() const {
202 * Total chain length, only valid if cacheLength was specified in the
205 size_t chainLength() const {
206 if (!options_.cacheChainLength) {
207 throw std::invalid_argument("IOBufQueue: chain length not cached");
212 const Options& options() const {
217 IOBufQueue(IOBufQueue&&);
218 IOBufQueue& operator=(IOBufQueue&&);
221 static const size_t kChainLengthNotCached = (size_t)-1;
223 IOBufQueue(const IOBufQueue&) = delete;
224 IOBufQueue& operator=(const IOBufQueue&) = delete;
228 /** Everything that has been appended but not yet discarded or moved out */
229 std::unique_ptr<folly::IOBuf> head_;
234 #endif // FOLLY_IO_IOBUF_QUEUE_H