folly/io/IOBufQueue.h

   1 /*
   2  * Copyright 2014 Facebook, Inc.
   3  *
   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
   7  *
   8  *   http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 #ifndef FOLLY_IO_IOBUF_QUEUE_H
  18 #define FOLLY_IO_IOBUF_QUEUE_H
  19
  20 #include "folly/io/IOBuf.h"
  21
  22 #include <stdexcept>
  23 #include <string>
  24
  25 namespace folly {
  26
  27 /**
  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.
  31  *
  32  * You may also prepend data into the headroom of the first buffer in the
  33  * chain, if any.
  34  */
  35 class IOBufQueue {
  36  public:
  37   struct Options {
  38     Options() : cacheChainLength(false) { }
  39     bool cacheChainLength;
  40   };
  41
  42   /**
  43    * Commonly used Options, currently the only possible value other than
  44    * the default.
  45    */
  46   static Options cacheChainLength() {
  47     Options options;
  48     options.cacheChainLength = true;
  49     return options;
  50   }
  51
  52   explicit IOBufQueue(const Options& options = Options());
  53
  54   /**
  55    * Return a space to prepend bytes and the amount of headroom available.
  56    */
  57   std::pair<void*, uint32_t> headroom();
  58
  59   /**
  60    * Indicate that n bytes from the headroom have been used.
  61    */
  62   void markPrepended(uint32_t n);
  63
  64   /**
  65    * Prepend an existing range; throws std::overflow_error if not enough
  66    * room.
  67    */
  68   void prepend(const void* buf, uint32_t n);
  69
  70   /**
  71    * Add a buffer or buffer chain to the end of this queue. The
  72    * queue takes ownership of buf.
  73    *
  74    * If pack is true, we try to reduce wastage at the end of this queue
  75    * by copying some data from the first buffers in the buf chain (and
  76    * releasing the buffers), if possible.  If pack is false, we leave
  77    * the chain topology unchanged.
  78    */
  79   void append(std::unique_ptr<folly::IOBuf>&& buf,
  80               bool pack=false);
  81
  82   /**
  83    * Add a queue to the end of this queue. The queue takes ownership of
  84    * all buffers from the other queue.
  85    */
  86   void append(IOBufQueue& other, bool pack=false);
  87   void append(IOBufQueue&& other, bool pack=false) {
  88     append(other, pack);  // call lvalue reference overload, above
  89   }
  90
  91   /**
  92    * Copy len bytes, starting at buf, to the end of this queue.
  93    * The caller retains ownership of the source data.
  94    */
  95   void append(const void* buf, size_t len);
  96
  97   /**
  98    * Copy a string to the end of this queue.
  99    * The caller retains ownership of the source data.
 100    */
 101   void append(const std::string& buf) {
 102     append(buf.data(), buf.length());
 103   }
 104
 105   /**
 106    * Append a chain of IOBuf objects that point to consecutive regions
 107    * within buf.
 108    *
 109    * Just like IOBuf::wrapBuffer, this should only be used when the caller
 110    * knows ahead of time and can ensure that all IOBuf objects that will point
 111    * to this buffer will be destroyed before the buffer itself is destroyed;
 112    * all other caveats from wrapBuffer also apply.
 113    *
 114    * Every buffer except for the last will wrap exactly blockSize bytes.
 115    * Importantly, this method may be used to wrap buffers larger than 4GB.
 116    */
 117   void wrapBuffer(const void* buf, size_t len,
 118                   uint32_t blockSize=(1U << 31));  // default block size: 2GB
 119
 120   /**
 121    * Obtain a writable block of contiguous bytes at the end of this
 122    * queue, allocating more space if necessary.  The amount of space
 123    * reserved will be at least min.  If min contiguous space is not
 124    * available at the end of the queue, and IOBuf with size newAllocationSize
 125    * is appended to the chain and returned.  The actual available space
 126    * may be larger than newAllocationSize, but will be truncated to max,
 127    * if specified.
 128    *
 129    * If the caller subsequently writes anything into the returned space,
 130    * it must call the postallocate() method.
 131    *
 132    * @return The starting address of the block and the length in bytes.
 133    *
 134    * @note The point of the preallocate()/postallocate() mechanism is
 135    *       to support I/O APIs such as Thrift's TAsyncSocket::ReadCallback
 136    *       that request a buffer from the application and then, in a later
 137    *       callback, tell the application how much of the buffer they've
 138    *       filled with data.
 139    */
 140   std::pair<void*,uint32_t> preallocate(
 141     uint32_t min, uint32_t newAllocationSize,
 142     uint32_t max = std::numeric_limits<uint32_t>::max()) {
 143     auto buf = tailBuf();
 144     if (LIKELY(buf && buf->tailroom() >= min)) {
 145       return std::make_pair(buf->writableTail(),
 146                             std::min(max, buf->tailroom()));
 147     }
 148
 149     return preallocateSlow(min, newAllocationSize, max);
 150   }
 151
 152   /**
 153    * Tell the queue that the caller has written data into the first n
 154    * bytes provided by the previous preallocate() call.
 155    *
 156    * @note n should be less than or equal to the size returned by
 157    *       preallocate().  If n is zero, the caller may skip the call
 158    *       to postallocate().  If n is nonzero, the caller must not
 159    *       invoke any other non-const methods on this IOBufQueue between
 160    *       the call to preallocate and the call to postallocate().
 161    */
 162   void postallocate(uint32_t n) {
 163     head_->prev()->append(n);
 164     chainLength_ += n;
 165   }
 166
 167   /**
 168    * Obtain a writable block of n contiguous bytes, allocating more space
 169    * if necessary, and mark it as used.  The caller can fill it later.
 170    */
 171   void* allocate(uint32_t n) {
 172     void* p = preallocate(n, n).first;
 173     postallocate(n);
 174     return p;
 175   }
 176
 177   void* writableTail() const {
 178     auto buf = tailBuf();
 179     return buf ? buf->writableTail() : nullptr;
 180   }
 181
 182   size_t tailroom() const {
 183     auto buf = tailBuf();
 184     return buf ? buf->tailroom() : 0;
 185   }
 186
 187   /**
 188    * Split off the first n bytes of the queue into a separate IOBuf chain,
 189    * and transfer ownership of the new chain to the caller.  The IOBufQueue
 190    * retains ownership of everything after the split point.
 191    *
 192    * @warning If the split point lies in the middle of some IOBuf within
 193    *          the chain, this function may, as an implementation detail,
 194    *          clone that IOBuf.
 195    *
 196    * @throws std::underflow_error if n exceeds the number of bytes
 197    *         in the queue.
 198    */
 199   std::unique_ptr<folly::IOBuf> split(size_t n);
 200
 201   /**
 202    * Similar to IOBuf::trimStart, but works on the whole queue.  Will
 203    * pop off buffers that have been completely trimmed.
 204    */
 205   void trimStart(size_t amount);
 206
 207   /**
 208    * Similar to IOBuf::trimEnd, but works on the whole queue.  Will
 209    * pop off buffers that have been completely trimmed.
 210    */
 211   void trimEnd(size_t amount);
 212
 213   /**
 214    * Transfer ownership of the queue's entire IOBuf chain to the caller.
 215    */
 216   std::unique_ptr<folly::IOBuf> move() {
 217     chainLength_ = 0;
 218     return std::move(head_);
 219   }
 220
 221   /**
 222    * Access
 223    */
 224   const folly::IOBuf* front() const {
 225     return head_.get();
 226   }
 227
 228   /**
 229    * returns the first IOBuf in the chain and removes it from the chain
 230    *
 231    * @return first IOBuf in the chain or nullptr if none.
 232    */
 233   std::unique_ptr<folly::IOBuf> pop_front();
 234
 235   /**
 236    * Total chain length, only valid if cacheLength was specified in the
 237    * constructor.
 238    */
 239   size_t chainLength() const {
 240     if (UNLIKELY(!options_.cacheChainLength)) {
 241       throw std::invalid_argument("IOBufQueue: chain length not cached");
 242     }
 243     return chainLength_;
 244   }
 245
 246   /**
 247    * Returns true iff the IOBuf chain length is 0.
 248    */
 249   bool empty() const {
 250     return !head_ || head_->empty();
 251   }
 252
 253   const Options& options() const {
 254     return options_;
 255   }
 256
 257   /**
 258    * Clear the queue.  Note that this does not release the buffers, it
 259    * just sets their length to zero; useful if you want to reuse the
 260    * same queue without reallocating.
 261    */
 262   void clear();
 263
 264   /** Movable */
 265   IOBufQueue(IOBufQueue&&);
 266   IOBufQueue& operator=(IOBufQueue&&);
 267
 268  private:
 269   IOBuf* tailBuf() const {
 270     if (UNLIKELY(!head_)) return nullptr;
 271     IOBuf* buf = head_->prev();
 272     return LIKELY(!buf->isSharedOne()) ? buf : nullptr;
 273   }
 274   std::pair<void*,uint32_t> preallocateSlow(
 275     uint32_t min, uint32_t newAllocationSize, uint32_t max);
 276
 277   static const size_t kChainLengthNotCached = (size_t)-1;
 278   /** Not copyable */
 279   IOBufQueue(const IOBufQueue&) = delete;
 280   IOBufQueue& operator=(const IOBufQueue&) = delete;
 281
 282   Options options_;
 283
 284   // NOTE that chainLength_ is still updated even if !options_.cacheChainLength
 285   // because doing it unchecked in postallocate() is faster (no (mis)predicted
 286   // branch)
 287   size_t chainLength_;
 288   /** Everything that has been appended but not yet discarded or moved out */
 289   std::unique_ptr<folly::IOBuf> head_;
 290 };
 291
 292 } // folly
 293
 294 #endif // FOLLY_IO_IOBUF_QUEUE_H