src/sbuf/MemBlob.h

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