xpcom/string/nsStringBuffer.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef nsStringBuffer_h__
   8 #define nsStringBuffer_h__
   9
  10 #include <atomic>
  11 #include "mozilla/MemoryReporting.h"
  12 #include "nsStringFwd.h"
  13
  14 template <class T>
  15 struct already_AddRefed;
  16
  17 /**
  18  * This structure precedes the string buffers "we" allocate.  It may be the
  19  * case that nsTAString::mData does not point to one of these special
  20  * buffers.  The mDataFlags member variable distinguishes the buffer type.
  21  *
  22  * When this header is in use, it enables reference counting, and capacity
  23  * tracking.  NOTE: A string buffer can be modified only if its reference
  24  * count is 1.
  25  */
  26 class nsStringBuffer {
  27  private:
  28   friend class CheckStaticAtomSizes;
  29
  30   std::atomic<uint32_t> mRefCount;
  31   uint32_t mStorageSize;
  32
  33  public:
  34   /**
  35    * Allocates a new string buffer, with given size in bytes and a
  36    * reference count of one.  When the string buffer is no longer needed,
  37    * it should be released via Release.
  38    *
  39    * It is up to the caller to set the bytes corresponding to the string
  40    * buffer by calling the Data method to fetch the raw data pointer.  Care
  41    * must be taken to properly null terminate the character array.  The
  42    * storage size can be greater than the length of the actual string
  43    * (i.e., it is not required that the null terminator appear in the last
  44    * storage unit of the string buffer's data).
  45    *
  46    * This guarantees that StorageSize() returns aStorageSize if the returned
  47    * buffer is non-null. Some callers like nsAttrValue rely on it.
  48    *
  49    * @return new string buffer or null if out of memory.
  50    */
  51   static already_AddRefed<nsStringBuffer> Alloc(size_t aStorageSize);
  52
  53   /**
  54    * Returns a string buffer initialized with the given string on it, or null on
  55    * OOM.
  56    * Note that this will allocate extra space for the trailing null byte, which
  57    * this method will add.
  58    */
  59   static already_AddRefed<nsStringBuffer> Create(const char16_t* aData,
  60                                                  size_t aLength);
  61   static already_AddRefed<nsStringBuffer> Create(const char* aData,
  62                                                  size_t aLength);
  63
  64   /**
  65    * Resizes the given string buffer to the specified storage size.  This
  66    * method must not be called on a readonly string buffer.  Use this API
  67    * carefully!!
  68    *
  69    * This method behaves like the ANSI-C realloc function.  (i.e., If the
  70    * allocation fails, null will be returned and the given string buffer
  71    * will remain unmodified.)
  72    *
  73    * @see IsReadonly
  74    */
  75   static nsStringBuffer* Realloc(nsStringBuffer* aBuf, size_t aStorageSize);
  76
  77   /**
  78    * Increment the reference count on this string buffer.
  79    */
  80   void NS_FASTCALL AddRef();
  81
  82   /**
  83    * Decrement the reference count on this string buffer.  The string
  84    * buffer will be destroyed when its reference count reaches zero.
  85    */
  86   void NS_FASTCALL Release();
  87
  88   /**
  89    * This method returns the string buffer corresponding to the given data
  90    * pointer.  The data pointer must have been returned previously by a
  91    * call to the nsStringBuffer::Data method.
  92    */
  93   static nsStringBuffer* FromData(void* aData) {
  94     return reinterpret_cast<nsStringBuffer*>(aData) - 1;
  95   }
  96
  97   /**
  98    * This method returns the data pointer for this string buffer.
  99    */
 100   void* Data() const {
 101     return const_cast<char*>(reinterpret_cast<const char*>(this + 1));
 102   }
 103
 104   /**
 105    * This function returns the storage size of a string buffer in bytes.
 106    * This value is the same value that was originally passed to Alloc (or
 107    * Realloc).
 108    */
 109   uint32_t StorageSize() const { return mStorageSize; }
 110
 111   /**
 112    * If this method returns false, then the caller can be sure that their
 113    * reference to the string buffer is the only reference to the string
 114    * buffer, and therefore it has exclusive access to the string buffer and
 115    * associated data.  However, if this function returns true, then other
 116    * consumers may rely on the data in this buffer being immutable and
 117    * other threads may access this buffer simultaneously.
 118    */
 119   bool IsReadonly() const {
 120     // This doesn't lead to the destruction of the buffer, so we don't
 121     // need to perform acquire memory synchronization for the normal
 122     // reason that a reference count needs acquire synchronization
 123     // (ensuring that all writes to the object made on other threads are
 124     // visible to the thread destroying the object).
 125     //
 126     // We then need to consider the possibility that there were prior
 127     // writes to the buffer on a different thread:  one that has either
 128     // since released its reference count, or one that also has access
 129     // to this buffer through the same reference.  There are two ways
 130     // for that to happen: either the buffer pointer or a data structure
 131     // (e.g., string object) pointing to the buffer was transferred from
 132     // one thread to another, or the data structure pointing to the
 133     // buffer was already visible on both threads.  In the first case
 134     // (transfer), the transfer of data from one thread to another would
 135     // have handled the memory synchronization.  In the latter case
 136     // (data structure visible on both threads), the caller needed some
 137     // sort of higher level memory synchronization to protect against
 138     // the string object being mutated at the same time on multiple
 139     // threads.
 140
 141     // See bug 1603504. TSan might complain about a race when using
 142     // memory_order_relaxed, so use memory_order_acquire for making TSan
 143     // happy.
 144 #if defined(MOZ_TSAN)
 145     return mRefCount.load(std::memory_order_acquire) > 1;
 146 #else
 147     return mRefCount.load(std::memory_order_relaxed) > 1;
 148 #endif
 149   }
 150
 151   /**
 152    * The FromString methods return a string buffer for the given string
 153    * object or null if the string object does not have a string buffer.
 154    * The reference count of the string buffer is NOT incremented by these
 155    * methods.  If the caller wishes to hold onto the returned value, then
 156    * the returned string buffer must have its reference count incremented
 157    * via a call to the AddRef method.
 158    */
 159   static nsStringBuffer* FromString(const nsAString& aStr);
 160   static nsStringBuffer* FromString(const nsACString& aStr);
 161
 162   /**
 163    * The ToString methods assign this string buffer to a given string
 164    * object.  If the string object does not support sharable string
 165    * buffers, then its value will be set to a copy of the given string
 166    * buffer.  Otherwise, these methods increment the reference count of the
 167    * given string buffer.  It is important to specify the length (in
 168    * storage units) of the string contained in the string buffer since the
 169    * length of the string may be less than its storage size.  The string
 170    * must have a null terminator at the offset specified by |len|.
 171    *
 172    * NOTE: storage size is measured in bytes even for wide strings;
 173    *       however, string length is always measured in storage units
 174    *       (2-byte units for wide strings).
 175    */
 176   void ToString(uint32_t aLen, nsAString& aStr, bool aMoveOwnership = false);
 177   void ToString(uint32_t aLen, nsACString& aStr, bool aMoveOwnership = false);
 178
 179   /**
 180    * This measures the size only if the StringBuffer is unshared.
 181    */
 182   size_t SizeOfIncludingThisIfUnshared(
 183       mozilla::MallocSizeOf aMallocSizeOf) const;
 184
 185   /**
 186    * This measures the size regardless of whether the StringBuffer is
 187    * unshared.
 188    *
 189    * WARNING: Only use this if you really know what you are doing, because
 190    * it can easily lead to double-counting strings.  If you do use them,
 191    * please explain clearly in a comment why it's safe and won't lead to
 192    * double-counting.
 193    */
 194   size_t SizeOfIncludingThisEvenIfShared(
 195       mozilla::MallocSizeOf aMallocSizeOf) const;
 196 };
 197
 198 #endif /* !defined(nsStringBuffer_h__ */