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_QUEUE_H
18 #define FOLLY_IO_IOBUF_QUEUE_H
20 #include "folly/experimental/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.
35 Options() : cacheChainLength(false) { }
36 bool cacheChainLength;
39 explicit IOBufQueue(const Options& options = Options());
42 * Add a buffer or buffer chain to the end of this queue. The
43 * queue takes ownership of buf.
45 void append(std::unique_ptr<folly::IOBuf>&& buf);
48 * Add a queue to the end of this queue. The queue takes ownership of
49 * all buffers from the other queue.
51 void append(IOBufQueue& other);
52 void append(IOBufQueue&& other) {
53 append(other); // call lvalue reference overload, above
57 * Copy len bytes, starting at buf, to the end of this queue.
58 * The caller retains ownership of the source data.
60 void append(const void* buf, size_t len);
63 * Copy a string to the end of this queue.
64 * The caller retains ownership of the source data.
66 void append(const std::string& buf) {
67 append(buf.data(), buf.length());
71 * Obtain a writable block of contiguous bytes at the end of this
72 * queue, allocating more space if necessary. The amount of space
73 * reserved will be between min and max, inclusive; the IOBufQueue
74 * implementation may pick a value in that range that makes efficient
75 * use of already-allocated internal space.
77 * If the caller subsequently writes anything into the returned space,
78 * it must call the postallocate() method.
80 * @return The starting address of the block and the length in bytes.
82 * @note The point of the preallocate()/postallocate() mechanism is
83 * to support I/O APIs such as Thrift's TAsyncSocket::ReadCallback
84 * that request a buffer from the application and then, in a later
85 * callback, tell the application how much of the buffer they've
88 std::pair<void*,uint32_t> preallocate(uint32_t min, uint32_t max);
91 * Tell the queue that the caller has written data into the first n
92 * bytes provided by the previous preallocate() call.
94 * @note n should be less than or equal to the size returned by
95 * preallocate(). If n is zero, the caller may skip the call
96 * to postallocate(). If n is nonzero, the caller must not
97 * invoke any other non-const methods on this IOBufQueue between
98 * the call to preallocate and the call to postallocate().
100 void postallocate(uint32_t n);
103 * Split off the first n bytes of the queue into a separate IOBuf chain,
104 * and transfer ownership of the new chain to the caller. The IOBufQueue
105 * retains ownership of everything after the split point.
107 * @warning If the split point lies in the middle of some IOBuf within
108 * the chain, this function may, as an implementation detail,
111 * @throws std::underflow_error if n exceeds the number of bytes
114 std::unique_ptr<folly::IOBuf> split(size_t n);
117 * Similar to IOBuf::trimStart, but works on the whole queue. Will
118 * pop off buffers that have been completely trimmed.
120 void trimStart(size_t amount);
123 * Similar to IOBuf::trimEnd, but works on the whole queue. Will
124 * pop off buffers that have been completely trimmed.
126 void trimEnd(size_t amount);
129 * Transfer ownership of the queue's entire IOBuf chain to the caller.
131 std::unique_ptr<folly::IOBuf>&& move() {
133 return std::move(head_);
139 const folly::IOBuf* front() const {
144 * Total chain length, only valid if cacheLength was specified in the
147 size_t chainLength() const {
148 if (!options_.cacheChainLength) {
149 throw std::invalid_argument("IOBufQueue: chain length not cached");
154 const Options& options() const {
159 IOBufQueue(IOBufQueue&&);
160 IOBufQueue& operator=(IOBufQueue&&);
163 static const size_t kChainLengthNotCached = (size_t)-1;
165 IOBufQueue(const IOBufQueue&) = delete;
166 IOBufQueue& operator=(const IOBufQueue&) = delete;
170 /** Everything that has been appended but not yet discarded or moved out */
171 std::unique_ptr<folly::IOBuf> head_;
176 #endif // FOLLY_IO_IOBUF_QUEUE_H