src/MemBlob.h

   1 /*
   2  * SQUID Web Proxy Cache          http://www.squid-cache.org/
   3  * ----------------------------------------------------------
   4  *
   5  *  Squid is the result of efforts by numerous individuals from
   6  *  the Internet community; see the CONTRIBUTORS file for full
   7  *  details.   Many organizations have provided support for Squid's
   8  *  development; see the SPONSORS file for full details.  Squid is
   9  *  Copyrighted (C) 2001 by the Regents of the University of
  10  *  California; see the COPYRIGHT file for full details.  Squid
  11  *  incorporates software developed and/or copyrighted by other
  12  *  sources; see the CREDITS file for full details.
  13  *
  14  *  This program is free software; you can redistribute it and/or modify
  15  *  it under the terms of the GNU General Public License as published by
  16  *  the Free Software Foundation; either version 2 of the License, or
  17  *  (at your option) any later version.
  18  *
  19  *  This program is distributed in the hope that it will be useful,
  20  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  *  GNU General Public License for more details.
  23  *
  24  *  You should have received a copy of the GNU General Public License
  25  *  along with this program; if not, write to the Free Software
  26  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
  27  */
  28
  29 #ifndef SQUID_MEMBLOB_H_
  30 #define SQUID_MEMBLOB_H_
  31
  32 #define MEMBLOB_DEBUGSECTION 24
  33
  34 #include "base/InstanceId.h"
  35 #include "base/RefCount.h"
  36 #include "MemPool.h"
  37
  38 /// Various MemBlob class-wide statistics.
  39 class MemBlobStats
  40 {
  41 public:
  42     MemBlobStats();
  43
  44     /// dumps class-wide statistics
  45     std::ostream& dump(std::ostream& os) const;
  46
  47     MemBlobStats& operator += (const MemBlobStats&);
  48
  49 public:
  50     uint64_t alloc;     ///< number of MemBlob instances created so far
  51     uint64_t live;      ///< number of MemBlob instances currently alive
  52     uint64_t append;    ///< number of MemBlob::append() calls
  53     uint64_t liveBytes; ///< the total size of currently allocated storage
  54 };
  55
  56 /** Refcountable, fixed-size, content-agnostic memory buffer.
  57  *
  58  * Allocated memory block is divided into two sequential areas:
  59  * "used memory" and "available space". The used area can be filled during
  60  * construction, grows via the append() call, and can be clear()ed.
  61  *
  62  * MemBlob users can cooperate to safely share the used area. However, MemBlob
  63  * provides weak use accounting and no sharing protections besides refcounting.
  64  */
  65 class MemBlob: public RefCountable
  66 {
  67 public:
  68     typedef RefCount<MemBlob> Pointer;
  69     typedef uint32_t size_type;
  70
  71     MEMPROXY_CLASS(MemBlob);
  72
  73     /// obtain a const view of class-wide statistics
  74     static const MemBlobStats& GetStats();
  75
  76     /// create a new MemBlob with at least reserveSize capacity
  77     explicit MemBlob(const size_type reserveSize);
  78
  79     /// create a MemBlob containing a copy of the buffer of a given size
  80     MemBlob(const char *buffer, const size_type bufferSize);
  81
  82     virtual ~MemBlob();
  83
  84     /// the number unused bytes at the end of the allocated blob
  85     size_type spaceSize() const { return capacity - size; }
  86
  87     /** check whether the caller can successfully append() n bytes
  88      *
  89      * \return true  the caller may append() n bytes to this blob now
  90      * \param off    the end of the blob area currently used by the caller
  91      * \param n      the total number of bytes the caller wants to append
  92      */
  93     bool canAppend(const size_type off, const size_type n) const {
  94         // TODO: ignore offset (and adjust size) when the blob is not shared?
  95         return isAppendOffset(off) && willFit(n);
  96     }
  97
  98     /** adjusts internal object state as if exactly n bytes were append()ed
  99      *
 100      * \throw TextException if there was not enough space in the blob
 101      * \param n the number of bytes that were appended
 102      */
 103     void appended(const size_type n);
 104
 105     /** copies exactly n bytes from the source to the available space area,
 106      *  enlarging the used area by n bytes
 107      *
 108      * \throw TextException if there is not enough space in the blob
 109      * \param source raw buffer to be copied
 110      * \param n the number of bytes to copy from the source buffer
 111      */
 112     void append(const char *source, const size_type n);
 113
 114     /// extends the available space to the entire allocated blob
 115     void clear() { size = 0; }
 116
 117     /// dump debugging information
 118     std::ostream & dump(std::ostream &os) const;
 119
 120 public:
 121     /* MemBlob users should avoid these and must treat them as read-only */
 122     char *mem;          ///< raw allocated memory block
 123     size_type capacity; ///< size of the raw allocated memory block
 124     size_type size;     ///< maximum allocated memory in use by callers
 125     const InstanceId<MemBlob> id; ///< blob identifier
 126
 127 private:
 128     static MemBlobStats Stats; ///< class-wide statistics
 129
 130     void memAlloc(const size_type memSize);
 131
 132     /// whether the offset points to the end of the used area
 133     bool isAppendOffset(const size_type off) const { return off == size; }
 134
 135     /// whether n more bytes can be appended
 136     bool willFit(const size_type n) const { return n <= spaceSize(); }
 137
 138     /* copying is not implemented */
 139     MemBlob(const MemBlob &);
 140     MemBlob& operator =(const MemBlob &);
 141 };
 142
 143 MEMPROXY_CLASS_INLINE(MemBlob);
 144
 145 #endif /* SQUID_MEMBLOB_H_ */