/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ /* vim: set ts=8 sts=2 et sw=2 tw=80: */ /* This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ #ifndef nsStringBuffer_h__ #define nsStringBuffer_h__ #include #include "mozilla/MemoryReporting.h" #include "mozilla/Assertions.h" #include "mozilla/AlreadyAddRefed.h" #include "mozilla/RefCounted.h" /** * This structure precedes the string buffers "we" allocate. It may be the * case that nsTAString::mData does not point to one of these special * buffers. The mDataFlags member variable distinguishes the buffer type. * * When this header is in use, it enables reference counting, and capacity * tracking. NOTE: A string buffer can be modified only if its reference * count is 1. */ class nsStringBuffer { private: std::atomic mRefCount; uint32_t mStorageSize; public: MOZ_DECLARE_REFCOUNTED_TYPENAME(nsStringBuffer) /** * Allocates a new string buffer, with given size in bytes and a * reference count of one. When the string buffer is no longer needed, * it should be released via Release. * * It is up to the caller to set the bytes corresponding to the string * buffer by calling the Data method to fetch the raw data pointer. Care * must be taken to properly null terminate the character array. The * storage size can be greater than the length of the actual string * (i.e., it is not required that the null terminator appear in the last * storage unit of the string buffer's data). * * This guarantees that StorageSize() returns aSize if the returned * buffer is non-null. Some callers like nsAttrValue rely on it. * * @return new string buffer or null if out of memory. */ static already_AddRefed Alloc(size_t aSize) { MOZ_ASSERT(aSize != 0, "zero capacity allocation not allowed"); MOZ_ASSERT(sizeof(nsStringBuffer) + aSize <= size_t(uint32_t(-1)) && sizeof(nsStringBuffer) + aSize > aSize, "mStorageSize will truncate"); auto* hdr = (nsStringBuffer*)malloc(sizeof(nsStringBuffer) + aSize); if (hdr) { hdr->mRefCount = 1; hdr->mStorageSize = aSize; mozilla::detail::RefCountLogger::logAddRef(hdr, 1); } return already_AddRefed(hdr); } /** * Returns a string buffer initialized with the given string on it, or null on * OOM. * Note that this will allocate extra space for the trailing null byte, which * this method will add. */ static already_AddRefed Create(const char16_t* aData, size_t aLength); static already_AddRefed Create(const char* aData, size_t aLength); /** * Resizes the given string buffer to the specified storage size. This * method must not be called on a readonly string buffer. Use this API * carefully!! * * This method behaves like the ANSI-C realloc function. (i.e., If the * allocation fails, null will be returned and the given string buffer * will remain unmodified.) * * @see IsReadonly */ static nsStringBuffer* Realloc(nsStringBuffer* aBuf, size_t aStorageSize); void AddRef() { // Memory synchronization is not required when incrementing a // reference count. The first increment of a reference count on a // thread is not important, since the first use of the object on a // thread can happen before it. What is important is the transfer // of the pointer to that thread, which may happen prior to the // first increment on that thread. The necessary memory // synchronization is done by the mechanism that transfers the // pointer between threads. uint32_t count = mRefCount.fetch_add(1, std::memory_order_relaxed) + 1; mozilla::detail::RefCountLogger::logAddRef(this, count); } void Release() { // Since this may be the last release on this thread, we need release // semantics so that prior writes on this thread are visible to the thread // that destroys the object when it reads mValue with acquire semantics. mozilla::detail::RefCountLogger::ReleaseLogger logger(this); uint32_t count = mRefCount.fetch_sub(1, std::memory_order_release) - 1; logger.logRelease(count); if (count == 0) { // We're going to destroy the object on this thread, so we need acquire // semantics to synchronize with the memory released by the last release // on other threads, that is, to ensure that writes prior to that release // are now visible on this thread. count = mRefCount.load(std::memory_order_acquire); free(this); // We were allocated with malloc. } } /** * This method returns the string buffer corresponding to the given data * pointer. The data pointer must have been returned previously by a * call to the nsStringBuffer::Data method. */ static nsStringBuffer* FromData(void* aData) { return reinterpret_cast(aData) - 1; } /** * This method returns the data pointer for this string buffer. */ void* Data() const { return const_cast(reinterpret_cast(this + 1)); } /** * This function returns the storage size of a string buffer in bytes. * This value is the same value that was originally passed to Alloc (or * Realloc). */ uint32_t StorageSize() const { return mStorageSize; } /** * If this method returns false, then the caller can be sure that their * reference to the string buffer is the only reference to the string * buffer, and therefore it has exclusive access to the string buffer and * associated data. However, if this function returns true, then other * consumers may rely on the data in this buffer being immutable and * other threads may access this buffer simultaneously. */ bool IsReadonly() const { // This doesn't lead to the destruction of the buffer, so we don't // need to perform acquire memory synchronization for the normal // reason that a reference count needs acquire synchronization // (ensuring that all writes to the object made on other threads are // visible to the thread destroying the object). // // We then need to consider the possibility that there were prior // writes to the buffer on a different thread: one that has either // since released its reference count, or one that also has access // to this buffer through the same reference. There are two ways // for that to happen: either the buffer pointer or a data structure // (e.g., string object) pointing to the buffer was transferred from // one thread to another, or the data structure pointing to the // buffer was already visible on both threads. In the first case // (transfer), the transfer of data from one thread to another would // have handled the memory synchronization. In the latter case // (data structure visible on both threads), the caller needed some // sort of higher level memory synchronization to protect against // the string object being mutated at the same time on multiple // threads. // See bug 1603504. TSan might complain about a race when using // memory_order_relaxed, so use memory_order_acquire for making TSan // happy. #if defined(MOZ_TSAN) return mRefCount.load(std::memory_order_acquire) > 1; #else return mRefCount.load(std::memory_order_relaxed) > 1; #endif } /** * This measures the size only if the StringBuffer is unshared. */ size_t SizeOfIncludingThisIfUnshared( mozilla::MallocSizeOf aMallocSizeOf) const; /** * This measures the size regardless of whether the StringBuffer is * unshared. * * WARNING: Only use this if you really know what you are doing, because * it can easily lead to double-counting strings. If you do use them, * please explain clearly in a comment why it's safe and won't lead to * double-counting. */ size_t SizeOfIncludingThisEvenIfShared( mozilla::MallocSizeOf aMallocSizeOf) const; }; #endif /* !defined(nsStringBuffer_h__ */