folly/experimental/io/IOBufQueue.h

   1 /*
   2  * Copyright 2012 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/experimental/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 class IOBufQueue {
  33  public:
  34   struct Options {
  35     Options() : cacheChainLength(false) { }
  36     bool cacheChainLength;
  37   };
  38
  39   explicit IOBufQueue(const Options& options = Options());
  40
  41   /**
  42    * Add a buffer or buffer chain to the end of this queue. The
  43    * queue takes ownership of buf.
  44    */
  45   void append(std::unique_ptr<folly::IOBuf>&& buf);
  46
  47   /**
  48    * Add a queue to the end of this queue. The queue takes ownership of
  49    * all buffers from the other queue.
  50    */
  51   void append(IOBufQueue& other);
  52   void append(IOBufQueue&& other) {
  53     append(other);  // call lvalue reference overload, above
  54   }
  55
  56   /**
  57    * Copy len bytes, starting at buf, to the end of this queue.
  58    * The caller retains ownership of the source data.
  59    */
  60   void append(const void* buf, size_t len);
  61
  62   /**
  63    * Copy a string to the end of this queue.
  64    * The caller retains ownership of the source data.
  65    */
  66   void append(const std::string& buf) {
  67     append(buf.data(), buf.length());
  68   }
  69
  70   /**
  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.
  76    *
  77    * If the caller subsequently writes anything into the returned space,
  78    * it must call the postallocate() method.
  79    *
  80    * @return The starting address of the block and the length in bytes.
  81    *
  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
  86    *       filled with data.
  87    */
  88   std::pair<void*,uint32_t> preallocate(uint32_t min, uint32_t max);
  89
  90   /**
  91    * Tell the queue that the caller has written data into the first n
  92    * bytes provided by the previous preallocate() call.
  93    *
  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().
  99    */
 100   void postallocate(uint32_t n);
 101
 102   /**
 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.
 106    *
 107    * @warning If the split point lies in the middle of some IOBuf within
 108    *          the chain, this function may, as an implementation detail,
 109    *          clone that IOBuf.
 110    *
 111    * @throws std::underflow_error if n exceeds the number of bytes
 112    *         in the queue.
 113    */
 114   std::unique_ptr<folly::IOBuf> split(size_t n);
 115
 116   /**
 117    * Similar to IOBuf::trimStart, but works on the whole queue.  Will
 118    * pop off buffers that have been completely trimmed.
 119    */
 120   void trimStart(size_t amount);
 121
 122   /**
 123    * Similar to IOBuf::trimEnd, but works on the whole queue.  Will
 124    * pop off buffers that have been completely trimmed.
 125    */
 126   void trimEnd(size_t amount);
 127
 128   /**
 129    * Transfer ownership of the queue's entire IOBuf chain to the caller.
 130    */
 131   std::unique_ptr<folly::IOBuf>&& move() {
 132     chainLength_ = 0;
 133     return std::move(head_);
 134   }
 135
 136   /**
 137    * Access
 138    */
 139   const folly::IOBuf* front() const {
 140     return head_.get();
 141   }
 142
 143   /**
 144    * Total chain length, only valid if cacheLength was specified in the
 145    * constructor.
 146    */
 147   size_t chainLength() const {
 148     if (!options_.cacheChainLength) {
 149       throw std::invalid_argument("IOBufQueue: chain length not cached");
 150     }
 151     return chainLength_;
 152   }
 153
 154   const Options& options() const {
 155     return options_;
 156   }
 157
 158   /** Movable */
 159   IOBufQueue(IOBufQueue&&);
 160   IOBufQueue& operator=(IOBufQueue&&);
 161
 162  private:
 163   static const size_t kChainLengthNotCached = (size_t)-1;
 164   /** Not copyable */
 165   IOBufQueue(const IOBufQueue&) = delete;
 166   IOBufQueue& operator=(const IOBufQueue&) = delete;
 167
 168   Options options_;
 169   size_t chainLength_;
 170   /** Everything that has been appended but not yet discarded or moved out */
 171   std::unique_ptr<folly::IOBuf> head_;
 172 };
 173
 174 } // folly
 175
 176 #endif // FOLLY_IO_IOBUF_QUEUE_H