src/MemBuf.h

   1 /*
   2  *
   3  * SQUID Web Proxy Cache          http://www.squid-cache.org/
   4  * ----------------------------------------------------------
   5  *
   6  *  Squid is the result of efforts by numerous individuals from
   7  *  the Internet community; see the CONTRIBUTORS file for full
   8  *  details.   Many organizations have provided support for Squid's
   9  *  development; see the SPONSORS file for full details.  Squid is
  10  *  Copyrighted (C) 2001 by the Regents of the University of
  11  *  California; see the COPYRIGHT file for full details.  Squid
  12  *  incorporates software developed and/or copyrighted by other
  13  *  sources; see the CREDITS file for full details.
  14  *
  15  *  This program is free software; you can redistribute it and/or modify
  16  *  it under the terms of the GNU General Public License as published by
  17  *  the Free Software Foundation; either version 2 of the License, or
  18  *  (at your option) any later version.
  19  *
  20  *  This program is distributed in the hope that it will be useful,
  21  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  22  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  23  *  GNU General Public License for more details.
  24  *
  25  *  You should have received a copy of the GNU General Public License
  26  *  along with this program; if not, write to the Free Software
  27  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
  28  *
  29  */
  30
  31 #ifndef SQUID_MEMBUF_H
  32 #define SQUID_MEMBUF_H
  33
  34 #include "cbdata.h"
  35 #include "Packer.h"
  36
  37 /**
  38  * Auto-growing memory-resident buffer with printf interface
  39  *
  40  \todo XXX: convert global memBuf*() functions into methods
  41  */
  42 class MemBuf
  43 {
  44
  45 public:
  46     _SQUID_INLINE_ MemBuf();
  47     _SQUID_INLINE_ ~MemBuf();
  48
  49     /// start of the added data
  50     char *content() { return buf; }
  51
  52     /// start of the added data
  53     const char *content() const { return buf; }
  54
  55     /// available data size
  56     mb_size_t contentSize() const { return size; }
  57
  58     /**
  59      * Whether the buffer contains any data.
  60      \retval true       if data exists in the buffer
  61      \retval false      if data exists in the buffer
  62      */
  63     bool hasContent() const { return size > 0; }
  64
  65     /// returns buffer after data; does not check space existence
  66     char *space() { return buf + size; } ///< space to add data
  67
  68     /// Returns buffer following data, after possibly growing the buffer to
  69     /// accommodate addition of the required bytes PLUS a 0-terminator char.
  70     /// The caller is not required to terminate the buffer, but MemBuf does
  71     /// terminate internally, trading termination for size calculation bugs.
  72     char *space(mb_size_t required) { if (size + required >= capacity) grow(size + required + 1); return buf + size; }
  73
  74     mb_size_t spaceSize() const;
  75
  76     /**
  77      * Whether the buffer contains any data space available.
  78      \retval true       if data can be added to the buffer
  79      \retval false      if the buffer is full
  80      */
  81     bool hasSpace() const { return size+1 < capacity; }
  82
  83     mb_size_t potentialSpaceSize() const; // accounts for possible growth
  84     bool hasPotentialSpace() const { return potentialSpaceSize() > 0; }
  85
  86     /// \note there is currently no stretch() method to grow without appending
  87
  88     void consume(mb_size_t sz);  // removes sz bytes, moving content left
  89     void consumeWhitespacePrefix();    ///< removes all prefix whitespace, moving content left
  90
  91     void append(const char *c, mb_size_t sz); // grows if needed and possible
  92     void appended(mb_size_t sz); // updates content size after external append
  93     void truncate(mb_size_t sz);  // removes sz last bytes
  94
  95     void terminate(); // zero-terminates the buffer w/o increasing contentSize
  96
  97     bool wasStolen() const { return stolen; }
  98
  99     /** init with specific sizes */
 100     void init(mb_size_t szInit, mb_size_t szMax);
 101
 102     /** init with defaults */
 103     void init();
 104
 105     /** cleans mb; last function to call if you do not give .buf away */
 106     void clean();
 107
 108     /** resets mb preserving (or initializing if needed) memory buffer */
 109     void reset();
 110
 111     /** unfirtunate hack to test if the buffer has been Init()ialized */
 112     int isNull();
 113
 114     /**
 115      * calls snprintf, extends buffer if needed
 116      \note  we use Printf instead of printf so the compiler won't
 117      *      think we're calling the libc printf()
 118      */
 119     void Printf(const char *fmt,...) PRINTF_FORMAT_ARG2;
 120
 121     /** vPrintf for other printf()'s to use */
 122     void vPrintf(const char *fmt, va_list ap);
 123
 124     /**
 125      * freezes the object! and returns function to clear it up.
 126      *
 127      \retval free() function to be used.
 128      */
 129     FREE *freeFunc();
 130
 131 private:
 132     /**
 133      * private copy constructor and assignment operator generates
 134      * compiler errors if someone tries to copy/assign a MemBuf
 135      */
 136     MemBuf(const MemBuf& m) {assert(false);};
 137
 138     MemBuf& operator= (const MemBuf& m) {assert(false); return *this;};
 139
 140     void grow(mb_size_t min_cap);
 141
 142 public:
 143     /**
 144      \deprecated use space*() and content*() methods to access safely instead.
 145      * public, read-only.
 146      *
 147      \todo XXX: hide these members completely and remove 0-termination
 148      *          so that consume() does not need to memmove all the time
 149      */
 150     char *buf;          // available content
 151     mb_size_t size;     // used space, does not count 0-terminator
 152
 153     /**
 154      * when grows: assert(new_capacity <= max_capacity)
 155      \deprecated Use interface function instead
 156      \todo XXX: make these private after converting memBuf*() functions to methods
 157      */
 158     mb_size_t max_capacity;
 159
 160     /**
 161      * allocated space
 162      \deprecated Use interface function instead
 163      \todo XXX: make these private after converting memBuf*() functions to methods
 164      */
 165     mb_size_t capacity;
 166
 167     unsigned stolen:1;          /* the buffer has been stolen for use by someone else */
 168
 169 #if 0
 170
 171     unsigned valid:1;           /* to be used for debugging only! */
 172 #endif
 173
 174 private:
 175     CBDATA_CLASS2(MemBuf);
 176 };
 177
 178 #if _USE_INLINE_
 179 #include "MemBuf.cci"
 180 #endif
 181
 182 /** returns free() function to be used, _freezes_ the object! */
 183 void memBufReport(MemBuf * mb);
 184 /** pack content into a mem buf. */
 185 void packerToMemInit(Packer * p, MemBuf * mb);
 186
 187 #endif /* SQUID_MEM_H */