src/sbuf/MemBlob.h

   1 /*
   2  * Copyright (C) 1996-2020 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_MEMBLOB_H_
  10 #define SQUID_MEMBLOB_H_
  11
  12 #define MEMBLOB_DEBUGSECTION 24
  13
  14 #include "base/InstanceId.h"
  15 #include "base/RefCount.h"
  16 #include "mem/forward.h"
  17
  18 /// Various MemBlob class-wide statistics.
  19 class MemBlobStats
  20 {
  21 public:
  22     MemBlobStats();
  23
  24     /// dumps class-wide statistics
  25     std::ostream& dump(std::ostream& os) const;
  26
  27     MemBlobStats& operator += (const MemBlobStats&);
  28
  29 public:
  30     uint64_t alloc;     ///< number of MemBlob instances created so far
  31     uint64_t live;      ///< number of MemBlob instances currently alive
  32     uint64_t append;    ///< number of MemBlob::append() calls
  33     uint64_t liveBytes; ///< the total size of currently allocated storage
  34 };
  35
  36 /** Refcountable, fixed-size, content-agnostic memory buffer.
  37  *
  38  * Allocated memory block is divided into two sequential areas:
  39  * "used memory" and "available space". The used area can be filled during
  40  * construction, grows via the append() call, and can be clear()ed.
  41  *
  42  * MemBlob users can cooperate to safely share the used area. However, MemBlob
  43  * provides weak use accounting and no sharing protections besides refcounting.
  44  */
  45 class MemBlob: public RefCountable
  46 {
  47     MEMPROXY_CLASS(MemBlob);
  48
  49 public:
  50     typedef RefCount<MemBlob> Pointer;
  51     typedef uint32_t size_type;
  52
  53     /// obtain a const view of class-wide statistics
  54     static const MemBlobStats& GetStats();
  55
  56     /// create a new MemBlob with at least reserveSize capacity
  57     explicit MemBlob(const size_type reserveSize);
  58
  59     /// create a MemBlob containing a copy of the buffer of a given size
  60     MemBlob(const char *buffer, const size_type bufferSize);
  61
  62     virtual ~MemBlob();
  63
  64     /// the number unused bytes at the end of the allocated blob
  65     size_type spaceSize() const { return capacity - size; }
  66
  67     /** check whether the caller can successfully append() n bytes
  68      *
  69      * \return true  the caller may append() n bytes to this blob now
  70      * \param off    the end of the blob area currently used by the caller
  71      * \param n      the total number of bytes the caller wants to append
  72      */
  73     bool canAppend(const size_type off, const size_type n) const {
  74         // TODO: ignore offset (and adjust size) when the blob is not shared?
  75         return (isAppendOffset(off) && willFit(n)) || !n;
  76     }
  77
  78     /** adjusts internal object state as if exactly n bytes were append()ed
  79      *
  80      * \throw TextException if there was not enough space in the blob
  81      * \param n the number of bytes that were appended
  82      */
  83     void appended(const size_type n);
  84
  85     /** copies exactly n bytes from the source to the available space area,
  86      *  enlarging the used area by n bytes
  87      *
  88      * \throw TextException if there is not enough space in the blob
  89      * \param source raw buffer to be copied
  90      * \param n the number of bytes to copy from the source buffer
  91      */
  92     void append(const char *source, const size_type n);
  93
  94     /// extends the available space to the entire allocated blob
  95     void clear() { size = 0; }
  96
  97     /// dump debugging information
  98     std::ostream & dump(std::ostream &os) const;
  99
 100 public:
 101     /* MemBlob users should avoid these and must treat them as read-only */
 102     char *mem;          ///< raw allocated memory block
 103     size_type capacity; ///< size of the raw allocated memory block
 104     size_type size;     ///< maximum allocated memory in use by callers
 105     const InstanceId<MemBlob> id; ///< blob identifier
 106
 107 private:
 108     static MemBlobStats Stats; ///< class-wide statistics
 109
 110     void memAlloc(const size_type memSize);
 111
 112     /// whether the offset points to the end of the used area
 113     bool isAppendOffset(const size_type off) const { return off == size; }
 114
 115     /// whether n more bytes can be appended
 116     bool willFit(const size_type n) const { return n <= spaceSize(); }
 117
 118     /* copying is not implemented */
 119     MemBlob(const MemBlob &);
 120     MemBlob& operator =(const MemBlob &);
 121 };
 122
 123 #endif /* SQUID_MEMBLOB_H_ */
 124