/* * Copyright 2012 Facebook, Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef FOLLY_IO_IOBUF_QUEUE_H #define FOLLY_IO_IOBUF_QUEUE_H #include "folly/experimental/io/IOBuf.h" #include #include namespace folly { /** * An IOBufQueue encapsulates a chain of IOBufs and provides * convenience functions to append data to the back of the chain * and remove data from the front. */ class IOBufQueue { public: struct Options { Options() : cacheChainLength(false) { } bool cacheChainLength; }; explicit IOBufQueue(const Options& options = Options()); /** * Add a buffer or buffer chain to the end of this queue. The * queue takes ownership of buf. */ void append(std::unique_ptr&& buf); /** * Add a queue to the end of this queue. The queue takes ownership of * all buffers from the other queue. */ void append(IOBufQueue& other); void append(IOBufQueue&& other) { append(other); // call lvalue reference overload, above } /** * Copy len bytes, starting at buf, to the end of this queue. * The caller retains ownership of the source data. */ void append(const void* buf, size_t len); /** * Copy a string to the end of this queue. * The caller retains ownership of the source data. */ void append(const std::string& buf) { append(buf.data(), buf.length()); } /** * Append a chain of IOBuf objects that point to consecutive regions * within buf. * * Just like IOBuf::wrapBuffer, this should only be used when the caller * knows ahead of time and can ensure that all IOBuf objects that will point * to this buffer will be destroyed before the buffer itself is destroyed; * all other caveats from wrapBuffer also apply. * * Every buffer except for the last will wrap exactly blockSize bytes. * Importantly, this method may be used to wrap buffers larger than 4GB. */ void wrapBuffer(const void* buf, size_t len, uint32_t blockSize=(1U << 31)); // default block size: 2GB /** * Obtain a writable block of contiguous bytes at the end of this * queue, allocating more space if necessary. The amount of space * reserved will be between min and max, inclusive; the IOBufQueue * implementation may pick a value in that range that makes efficient * use of already-allocated internal space. * * If the caller subsequently writes anything into the returned space, * it must call the postallocate() method. * * @return The starting address of the block and the length in bytes. * * @note The point of the preallocate()/postallocate() mechanism is * to support I/O APIs such as Thrift's TAsyncSocket::ReadCallback * that request a buffer from the application and then, in a later * callback, tell the application how much of the buffer they've * filled with data. */ std::pair preallocate(uint32_t min, uint32_t max); /** * Tell the queue that the caller has written data into the first n * bytes provided by the previous preallocate() call. * * @note n should be less than or equal to the size returned by * preallocate(). If n is zero, the caller may skip the call * to postallocate(). If n is nonzero, the caller must not * invoke any other non-const methods on this IOBufQueue between * the call to preallocate and the call to postallocate(). */ void postallocate(uint32_t n); /** * Obtain a writable block of n contiguous bytes, allocating more space * if necessary, and mark it as used. The caller can fill it later. */ void* allocate(uint32_t n) { void* p = preallocate(n, n).first; postallocate(n); return p; } /** * Split off the first n bytes of the queue into a separate IOBuf chain, * and transfer ownership of the new chain to the caller. The IOBufQueue * retains ownership of everything after the split point. * * @warning If the split point lies in the middle of some IOBuf within * the chain, this function may, as an implementation detail, * clone that IOBuf. * * @throws std::underflow_error if n exceeds the number of bytes * in the queue. */ std::unique_ptr split(size_t n); /** * Similar to IOBuf::trimStart, but works on the whole queue. Will * pop off buffers that have been completely trimmed. */ void trimStart(size_t amount); /** * Similar to IOBuf::trimEnd, but works on the whole queue. Will * pop off buffers that have been completely trimmed. */ void trimEnd(size_t amount); /** * Transfer ownership of the queue's entire IOBuf chain to the caller. */ std::unique_ptr&& move() { chainLength_ = 0; return std::move(head_); } /** * Access */ const folly::IOBuf* front() const { return head_.get(); } /** * Total chain length, only valid if cacheLength was specified in the * constructor. */ size_t chainLength() const { if (!options_.cacheChainLength) { throw std::invalid_argument("IOBufQueue: chain length not cached"); } return chainLength_; } const Options& options() const { return options_; } /** Movable */ IOBufQueue(IOBufQueue&&); IOBufQueue& operator=(IOBufQueue&&); private: static const size_t kChainLengthNotCached = (size_t)-1; /** Not copyable */ IOBufQueue(const IOBufQueue&) = delete; IOBufQueue& operator=(const IOBufQueue&) = delete; Options options_; size_t chainLength_; /** Everything that has been appended but not yet discarded or moved out */ std::unique_ptr head_; }; } // folly #endif // FOLLY_IO_IOBUF_QUEUE_H