src/MemBuf.h

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