src/MemBuf.h

   1 /*
   2  * Copyright (C) 1996-2014 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 #ifndef SQUID_MEMBUF_H
  10 #define SQUID_MEMBUF_H
  11
  12 #include "cbdata.h"
  13 #include "Packer.h"
  14
  15 /**
  16  * Auto-growing memory-resident buffer with printf interface
  17  * \deprecated Use SBuf instead.
  18  */
  19 class MemBuf
  20 {
  21     CBDATA_CLASS(MemBuf);
  22
  23 public:
  24     MemBuf():
  25         buf(NULL),
  26         size(0),
  27         max_capacity(0),
  28         capacity(0),
  29         stolen(0)
  30     {}
  31     ~MemBuf() {
  32         if (!stolen && buf)
  33             clean();
  34     }
  35
  36     /// start of the added data
  37     char *content() { return buf; }
  38
  39     /// start of the added data
  40     const char *content() const { return buf; }
  41
  42     /// available data size
  43     mb_size_t contentSize() const { return size; }
  44
  45     /**
  46      * Whether the buffer contains any data.
  47      \retval true   if data exists in the buffer
  48      \retval false  if data exists in the buffer
  49      */
  50     bool hasContent() const { return size > 0; }
  51
  52     /// returns buffer after data; does not check space existence
  53     char *space() { return buf + size; } ///< space to add data
  54
  55     /// Returns buffer following data, after possibly growing the buffer to
  56     /// accommodate addition of the required bytes PLUS a 0-terminator char.
  57     /// The caller is not required to terminate the buffer, but MemBuf does
  58     /// terminate internally, trading termination for size calculation bugs.
  59     char *space(mb_size_t required) { if (size + required >= capacity) grow(size + required + 1); return buf + size; }
  60
  61     mb_size_t spaceSize() const;
  62
  63     /**
  64      * Whether the buffer contains any data space available.
  65      \retval true   if data can be added to the buffer
  66      \retval false  if the buffer is full
  67      */
  68     bool hasSpace() const { return size+1 < capacity; }
  69
  70     mb_size_t potentialSpaceSize() const; // accounts for possible growth
  71     bool hasPotentialSpace() const { return potentialSpaceSize() > 0; }
  72
  73     /// \note there is currently no stretch() method to grow without appending
  74
  75     void consume(mb_size_t sz);  // removes sz bytes, moving content left
  76     void consumeWhitespacePrefix();    ///< removes all prefix whitespace, moving content left
  77
  78     void append(const char *c, mb_size_t sz); // grows if needed and possible
  79     void appended(mb_size_t sz); // updates content size after external append
  80     void truncate(mb_size_t sz);  // removes sz last bytes
  81
  82     void terminate(); // zero-terminates the buffer w/o increasing contentSize
  83
  84     bool wasStolen() const { return stolen; }
  85
  86     /** init with specific sizes */
  87     void init(mb_size_t szInit, mb_size_t szMax);
  88
  89     /** init with defaults */
  90     void init();
  91
  92     /** cleans mb; last function to call if you do not give .buf away */
  93     void clean();
  94
  95     /** resets mb preserving (or initializing if needed) memory buffer */
  96     void reset();
  97
  98     /** unfirtunate hack to test if the buffer has been Init()ialized */
  99     int isNull();
 100
 101     /**
 102      * calls snprintf, extends buffer if needed
 103      \note  we use Printf instead of printf so the compiler won't
 104      *      think we're calling the libc printf()
 105      */
 106     void Printf(const char *fmt,...) PRINTF_FORMAT_ARG2;
 107
 108     /** vPrintf for other printf()'s to use */
 109     void vPrintf(const char *fmt, va_list ap);
 110
 111     /**
 112      * freezes the object! and returns function to clear it up.
 113      *
 114      \retval free() function to be used.
 115      */
 116     FREE *freeFunc();
 117
 118 private:
 119     /**
 120      * private copy constructor and assignment operator generates
 121      * compiler errors if someone tries to copy/assign a MemBuf
 122      */
 123     MemBuf(const MemBuf& m) {assert(false);};
 124
 125     MemBuf& operator= (const MemBuf& m) {assert(false); return *this;};
 126
 127     void grow(mb_size_t min_cap);
 128
 129 public:
 130     /**
 131      \deprecated use space*() and content*() methods to access safely instead.
 132      * public, read-only.
 133      *
 134      * TODO: hide these members completely and remove 0-termination
 135      *          so that consume() does not need to memmove all the time
 136      */
 137     char *buf;          // available content
 138     mb_size_t size;     // used space, does not count 0-terminator
 139
 140     /**
 141      * when grows: assert(new_capacity <= max_capacity)
 142      * \deprecated Use interface function instead
 143      * TODO: make these private after converting memBuf*() functions to methods
 144      */
 145     mb_size_t max_capacity;
 146
 147     /**
 148      * allocated space
 149      * \deprecated Use interface function instead
 150      * TODO: make these private after converting memBuf*() functions to methods
 151      */
 152     mb_size_t capacity;
 153
 154     unsigned stolen:1;      /* the buffer has been stolen for use by someone else */
 155
 156 #if 0
 157
 158     unsigned valid:1;       /* to be used for debugging only! */
 159 #endif
 160 };
 161
 162 /** returns free() function to be used, _freezes_ the object! */
 163 void memBufReport(MemBuf * mb);
 164 /** pack content into a mem buf. */
 165 void packerToMemInit(Packer * p, MemBuf * mb);
 166
 167 #endif /* SQUID_MEMBUF_H */
 168