Adding upstream version 115.7.0esr.upstream/115.7.0esr

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 999 insertions, 0 deletions

diff --git a/mozglue/baseprofiler/public/BlocksRingBuffer.h b/mozglue/baseprofiler/public/BlocksRingBuffer.h
new file mode 100644
index 0000000000..32cbe6b93c
--- /dev/null
+++ b/mozglue/baseprofiler/public/BlocksRingBuffer.h
@@ -0,0 +1,999 @@
+/* -*- Mode: C++; tab-width: 2; 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 BlocksRingBuffer_h
+#define BlocksRingBuffer_h
+
+#include "mozilla/BaseProfilerDetail.h"
+#include "mozilla/ModuloBuffer.h"
+#include "mozilla/ProfileBufferIndex.h"
+#include "mozilla/ScopeExit.h"
+
+#include <functional>
+#include <string>
+#include <tuple>
+#include <utility>
+
+namespace mozilla {
+
+// Thread-safe Ring buffer that can store blocks of different sizes during
+// defined sessions.
+// Each *block* contains an *entry* and the entry size:
+// [ entry_size | entry ] [ entry_size | entry ] ...
+// *In-session* is a period of time during which `BlocksRingBuffer` allows
+// reading and writing. *Out-of-session*, the `BlocksRingBuffer` object is
+// still valid, but contains no data, and gracefully denies accesses.
+//
+// To write an entry, the buffer reserves a block of sufficient size (to contain
+// user data of predetermined size), writes the entry size, and lets the caller
+// fill the entry contents using ModuloBuffer::Iterator APIs and a few entry-
+// specific APIs. E.g.:
+// ```
+// BlockRingsBuffer brb(PowerOfTwo<BlockRingsBuffer::Length>(1024));
+// brb.ReserveAndPut([]() { return sizeof(123); },
+//                   [&](ProfileBufferEntryWriter& aEW) {
+//                     aEW.WriteObject(123);
+//                   });
+// ```
+// Other `Put...` functions may be used as shortcuts for simple entries.
+// The objects given to the caller's callbacks should only be used inside the
+// callbacks and not stored elsewhere, because they keep their own references to
+// the BlocksRingBuffer and therefore should not live longer.
+// Different type of objects may be serialized into an entry, see `Serializer`
+// for more information.
+//
+// When reading data, the buffer iterates over blocks (it knows how to read the
+// entry size, and therefore move to the next block), and lets the caller read
+// the entry inside of each block. E.g.:
+// ```
+// brb.Read([](BlocksRingBuffer::Reader aR) {}
+//   for (ProfileBufferEntryReader aER : aR) {
+//     /* Use ProfileBufferEntryReader functions to read serialized objects. */
+//     int n = aER.ReadObject<int>();
+//   }
+// });
+// ```
+// Different type of objects may be deserialized from an entry, see
+// `Deserializer` for more information.
+//
+// The caller may retrieve the `ProfileBufferBlockIndex` corresponding to an
+// entry (`ProfileBufferBlockIndex` is an opaque type preventing the user from
+// modifying it). That index may later be used to get back to that particular
+// entry if it still exists.
+class BlocksRingBuffer {
+ public:
+  // Using ModuloBuffer as underlying circular byte buffer.
+  using Buffer = ModuloBuffer<uint32_t, ProfileBufferIndex>;
+  using Byte = Buffer::Byte;
+
+  // Length type for total buffer (as PowerOfTwo<Length>) and each entry.
+  using Length = uint32_t;
+
+  enum class ThreadSafety { WithoutMutex, WithMutex };
+
+  // Default constructor starts out-of-session (nothing to read or write).
+  explicit BlocksRingBuffer(ThreadSafety aThreadSafety)
+      : mMutex(aThreadSafety != ThreadSafety::WithoutMutex) {}
+
+  // Create a buffer of the given length.
+  explicit BlocksRingBuffer(ThreadSafety aThreadSafety,
+                            PowerOfTwo<Length> aLength)
+      : mMutex(aThreadSafety != ThreadSafety::WithoutMutex),
+        mMaybeUnderlyingBuffer(Some(UnderlyingBuffer(aLength))) {}
+
+  // Take ownership of an existing buffer.
+  BlocksRingBuffer(ThreadSafety aThreadSafety,
+                   UniquePtr<Buffer::Byte[]> aExistingBuffer,
+                   PowerOfTwo<Length> aLength)
+      : mMutex(aThreadSafety != ThreadSafety::WithoutMutex),
+        mMaybeUnderlyingBuffer(
+            Some(UnderlyingBuffer(std::move(aExistingBuffer), aLength))) {}
+
+  // Use an externally-owned buffer.
+  BlocksRingBuffer(ThreadSafety aThreadSafety, Buffer::Byte* aExternalBuffer,
+                   PowerOfTwo<Length> aLength)
+      : mMutex(aThreadSafety != ThreadSafety::WithoutMutex),
+        mMaybeUnderlyingBuffer(
+            Some(UnderlyingBuffer(aExternalBuffer, aLength))) {}
+
+  // Destructor doesn't need to do anything special. (Clearing entries would
+  // only update indices and stats, which won't be accessible after the object
+  // is destroyed anyway.)
+  ~BlocksRingBuffer() = default;
+
+  // Remove underlying buffer, if any.
+  void Reset() {
+    baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
+    ResetUnderlyingBuffer();
+  }
+
+  // Create a buffer of the given length.
+  void Set(PowerOfTwo<Length> aLength) {
+    baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
+    ResetUnderlyingBuffer();
+    mMaybeUnderlyingBuffer.emplace(aLength);
+  }
+
+  // Take ownership of an existing buffer.
+  void Set(UniquePtr<Buffer::Byte[]> aExistingBuffer,
+           PowerOfTwo<Length> aLength) {
+    baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
+    ResetUnderlyingBuffer();
+    mMaybeUnderlyingBuffer.emplace(std::move(aExistingBuffer), aLength);
+  }
+
+  // Use an externally-owned buffer.
+  void Set(Buffer::Byte* aExternalBuffer, PowerOfTwo<Length> aLength) {
+    baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
+    ResetUnderlyingBuffer();
+    mMaybeUnderlyingBuffer.emplace(aExternalBuffer, aLength);
+  }
+
+  // This cannot change during the lifetime of this buffer, so there's no need
+  // to lock.
+  bool IsThreadSafe() const { return mMutex.IsActivated(); }
+
+  [[nodiscard]] bool IsInSession() const {
+    baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
+    return !!mMaybeUnderlyingBuffer;
+  }
+
+  // Lock the buffer mutex and run the provided callback.
+  // This can be useful when the caller needs to explicitly lock down this
+  // buffer, but not do anything else with it.
+  template <typename Callback>
+  auto LockAndRun(Callback&& aCallback) const {
+    baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
+    return std::forward<Callback>(aCallback)();
+  }
+
+  // Buffer length in bytes.
+  Maybe<PowerOfTwo<Length>> BufferLength() const {
+    baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
+    return mMaybeUnderlyingBuffer.map([](const UnderlyingBuffer& aBuffer) {
+      return aBuffer.mBuffer.BufferLength();
+    });
+    ;
+  }
+
+  // Size of external resources.
+  size_t SizeOfExcludingThis(MallocSizeOf aMallocSizeOf) const {
+    if (!mMaybeUnderlyingBuffer) {
+      return 0;
+    }
+    return mMaybeUnderlyingBuffer->mBuffer.SizeOfExcludingThis(aMallocSizeOf);
+  }
+
+  size_t SizeOfIncludingThis(MallocSizeOf aMallocSizeOf) const {
+    return aMallocSizeOf(this) + SizeOfExcludingThis(aMallocSizeOf);
+  }
+
+  // Snapshot of the buffer state.
+  struct State {
+    // Index to the first block.
+    ProfileBufferBlockIndex mRangeStart;
+
+    // Index past the last block. Equals mRangeStart if empty.
+    ProfileBufferBlockIndex mRangeEnd;
+
+    // Number of blocks that have been pushed into this buffer.
+    uint64_t mPushedBlockCount = 0;
+
+    // Number of blocks that have been removed from this buffer.
+    // Note: Live entries = pushed - cleared.
+    uint64_t mClearedBlockCount = 0;
+  };
+
+  // Get a snapshot of the current state.
+  // When out-of-session, mFirstReadIndex==mNextWriteIndex, and
+  // mPushedBlockCount==mClearedBlockCount==0.
+  // Note that these may change right after this thread-safe call, so they
+  // should only be used for statistical purposes.
+  State GetState() const {
+    baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
+    return {
+        mFirstReadIndex, mNextWriteIndex,
+        mMaybeUnderlyingBuffer ? mMaybeUnderlyingBuffer->mPushedBlockCount : 0,
+        mMaybeUnderlyingBuffer ? mMaybeUnderlyingBuffer->mClearedBlockCount
+                               : 0};
+  }
+
+  class Reader;
+
+  // Class that can iterate through blocks and provide
+  // `ProfileBufferEntryReader`s.
+  // Created through `Reader`, lives within a lock guard lifetime.
+  class BlockIterator {
+   public:
+#ifdef DEBUG
+    ~BlockIterator() {
+      // No BlockIterator should live outside of a mutexed call.
+      mRing->mMutex.AssertCurrentThreadOwns();
+    }
+#endif  // DEBUG
+
+    // Comparison with other iterator, mostly used in range-for loops.
+    bool operator==(const BlockIterator aRhs) const {
+      MOZ_ASSERT(mRing == aRhs.mRing);
+      return mBlockIndex == aRhs.mBlockIndex;
+    }
+    bool operator!=(const BlockIterator aRhs) const {
+      MOZ_ASSERT(mRing == aRhs.mRing);
+      return mBlockIndex != aRhs.mBlockIndex;
+    }
+
+    // Advance to next BlockIterator.
+    BlockIterator& operator++() {
+      mBlockIndex = NextBlockIndex();
+      return *this;
+    }
+
+    // Dereferencing creates a `ProfileBufferEntryReader` for the entry inside
+    // this block.
+    ProfileBufferEntryReader operator*() const {
+      return mRing->ReaderInBlockAt(mBlockIndex);
+    }
+
+    // True if this iterator is just past the last entry.
+    bool IsAtEnd() const {
+      MOZ_ASSERT(mBlockIndex <= BufferRangeEnd());
+      return mBlockIndex == BufferRangeEnd();
+    }
+
+    // Can be used as reference to come back to this entry with `ReadAt()`.
+    ProfileBufferBlockIndex CurrentBlockIndex() const { return mBlockIndex; }
+
+    // Index past the end of this block, which is the start of the next block.
+    ProfileBufferBlockIndex NextBlockIndex() const {
+      MOZ_ASSERT(!IsAtEnd());
+      const Length entrySize =
+          mRing->ReaderInBlockAt(mBlockIndex).RemainingBytes();
+      return ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
+          mBlockIndex.ConvertToProfileBufferIndex() + ULEB128Size(entrySize) +
+          entrySize);
+    }
+
+    // Index of the first block in the whole buffer.
+    ProfileBufferBlockIndex BufferRangeStart() const {
+      return mRing->mFirstReadIndex;
+    }
+
+    // Index past the last block in the whole buffer.
+    ProfileBufferBlockIndex BufferRangeEnd() const {
+      return mRing->mNextWriteIndex;
+    }
+
+   private:
+    // Only a Reader can instantiate a BlockIterator.
+    friend class Reader;
+
+    BlockIterator(const BlocksRingBuffer& aRing,
+                  ProfileBufferBlockIndex aBlockIndex)
+        : mRing(WrapNotNull(&aRing)), mBlockIndex(aBlockIndex) {
+      // No BlockIterator should live outside of a mutexed call.
+      mRing->mMutex.AssertCurrentThreadOwns();
+    }
+
+    // Using a non-null pointer instead of a reference, to allow copying.
+    // This BlockIterator should only live inside one of the thread-safe
+    // BlocksRingBuffer functions, for this reference to stay valid.
+    NotNull<const BlocksRingBuffer*> mRing;
+    ProfileBufferBlockIndex mBlockIndex;
+  };
+
+  // Class that can create `BlockIterator`s (e.g., for range-for), or just
+  // iterate through entries; lives within a lock guard lifetime.
+  class MOZ_RAII Reader {
+   public:
+    Reader(const Reader&) = delete;
+    Reader& operator=(const Reader&) = delete;
+    Reader(Reader&&) = delete;
+    Reader& operator=(Reader&&) = delete;
+
+#ifdef DEBUG
+    ~Reader() {
+      // No Reader should live outside of a mutexed call.
+      mRing.mMutex.AssertCurrentThreadOwns();
+    }
+#endif  // DEBUG
+
+    // Index of the first block in the whole buffer.
+    ProfileBufferBlockIndex BufferRangeStart() const {
+      return mRing.mFirstReadIndex;
+    }
+
+    // Index past the last block in the whole buffer.
+    ProfileBufferBlockIndex BufferRangeEnd() const {
+      return mRing.mNextWriteIndex;
+    }
+
+    // Iterators to the first and past-the-last blocks.
+    // Compatible with range-for (see `ForEach` below as example).
+    BlockIterator begin() const {
+      return BlockIterator(mRing, BufferRangeStart());
+    }
+    // Note that a `BlockIterator` at the `end()` should not be dereferenced, as
+    // there is no actual block there!
+    BlockIterator end() const { return BlockIterator(mRing, BufferRangeEnd()); }
+
+    // Get a `BlockIterator` at the given `ProfileBufferBlockIndex`, clamped to
+    // the stored range. Note that a `BlockIterator` at the `end()` should not
+    // be dereferenced, as there is no actual block there!
+    BlockIterator At(ProfileBufferBlockIndex aBlockIndex) const {
+      if (aBlockIndex < BufferRangeStart()) {
+        // Anything before the range (including null ProfileBufferBlockIndex) is
+        // clamped at the beginning.
+        return begin();
+      }
+      // Otherwise we at least expect the index to be valid (pointing exactly at
+      // a live block, or just past the end.)
+      mRing.AssertBlockIndexIsValidOrEnd(aBlockIndex);
+      return BlockIterator(mRing, aBlockIndex);
+    }
+
+    // Run `aCallback(ProfileBufferEntryReader&)` on each entry from first to
+    // last. Callback should not store `ProfileBufferEntryReader`, as it may
+    // become invalid after this thread-safe call.
+    template <typename Callback>
+    void ForEach(Callback&& aCallback) const {
+      for (ProfileBufferEntryReader reader : *this) {
+        aCallback(reader);
+      }
+    }
+
+   private:
+    friend class BlocksRingBuffer;
+
+    explicit Reader(const BlocksRingBuffer& aRing) : mRing(aRing) {
+      // No Reader should live outside of a mutexed call.
+      mRing.mMutex.AssertCurrentThreadOwns();
+    }
+
+    // This Reader should only live inside one of the thread-safe
+    // BlocksRingBuffer functions, for this reference to stay valid.
+    const BlocksRingBuffer& mRing;
+  };
+
+  // Call `aCallback(BlocksRingBuffer::Reader*)` (nullptr when out-of-session),
+  // and return whatever `aCallback` returns. Callback should not store
+  // `Reader`, because it may become invalid after this call.
+  template <typename Callback>
+  auto Read(Callback&& aCallback) const {
+    {
+      baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
+      if (MOZ_LIKELY(mMaybeUnderlyingBuffer)) {
+        Reader reader(*this);
+        return std::forward<Callback>(aCallback)(&reader);
+      }
+    }
+    return std::forward<Callback>(aCallback)(nullptr);
+  }
+
+  // Call `aCallback(ProfileBufferEntryReader&)` on each item.
+  // Callback should not store `ProfileBufferEntryReader`, because it may become
+  // invalid after this call.
+  template <typename Callback>
+  void ReadEach(Callback&& aCallback) const {
+    Read([&](Reader* aReader) {
+      if (MOZ_LIKELY(aReader)) {
+        aReader->ForEach(aCallback);
+      }
+    });
+  }
+
+  // Call `aCallback(Maybe<ProfileBufferEntryReader>&&)` on the entry at
+  // the given ProfileBufferBlockIndex; The `Maybe` will be `Nothing` if
+  // out-of-session, or if that entry doesn't exist anymore, or if we've reached
+  // just past the last entry. Return whatever `aCallback` returns. Callback
+  // should not store `ProfileBufferEntryReader`, because it may become invalid
+  // after this call.
+  template <typename Callback>
+  auto ReadAt(ProfileBufferBlockIndex aBlockIndex, Callback&& aCallback) const {
+    baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
+    MOZ_ASSERT(aBlockIndex <= mNextWriteIndex);
+    Maybe<ProfileBufferEntryReader> maybeEntryReader;
+    if (MOZ_LIKELY(mMaybeUnderlyingBuffer) && aBlockIndex >= mFirstReadIndex &&
+        aBlockIndex < mNextWriteIndex) {
+      AssertBlockIndexIsValid(aBlockIndex);
+      maybeEntryReader.emplace(ReaderInBlockAt(aBlockIndex));
+    }
+    return std::forward<Callback>(aCallback)(std::move(maybeEntryReader));
+  }
+
+  // Main function to write entries.
+  // Reserve `aCallbackBytes()` bytes, call `aCallback()` with a pointer to an
+  // on-stack temporary ProfileBufferEntryWriter (nullptr when out-of-session),
+  // and return whatever `aCallback` returns. Callback should not store
+  // `ProfileBufferEntryWriter`, because it may become invalid after this
+  // thread-safe call. Note: `aCallbackBytes` is a callback instead of a simple
+  // value, to delay this potentially-expensive computation until after we're
+  // checked that we're in-session; use `Put(Length, Callback)` below if you
+  // know the size already.
+  template <typename CallbackBytes, typename Callback>
+  auto ReserveAndPut(CallbackBytes aCallbackBytes, Callback&& aCallback) {
+    Maybe<ProfileBufferEntryWriter> maybeEntryWriter;
+
+    baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
+
+    if (MOZ_LIKELY(mMaybeUnderlyingBuffer)) {
+      const Length entryBytes = std::forward<CallbackBytes>(aCallbackBytes)();
+      MOZ_RELEASE_ASSERT(entryBytes > 0);
+      const Length bufferBytes =
+          mMaybeUnderlyingBuffer->mBuffer.BufferLength().Value();
+      MOZ_RELEASE_ASSERT(entryBytes <= bufferBytes - ULEB128Size(entryBytes),
+                         "Entry would wrap and overwrite itself");
+      // Compute block size from the requested entry size.
+      const Length blockBytes = ULEB128Size(entryBytes) + entryBytes;
+      // We will put this new block at the end of the current buffer.
+      const ProfileBufferIndex blockIndex =
+          mNextWriteIndex.ConvertToProfileBufferIndex();
+      // Compute the end of this new block.
+      const ProfileBufferIndex blockEnd = blockIndex + blockBytes;
+      while (blockEnd >
+             mFirstReadIndex.ConvertToProfileBufferIndex() + bufferBytes) {
+        // About to trample on an old block.
+        ProfileBufferEntryReader reader = ReaderInBlockAt(mFirstReadIndex);
+        mMaybeUnderlyingBuffer->mClearedBlockCount += 1;
+        // Move the buffer reading start past this cleared block.
+        mFirstReadIndex = ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
+            mFirstReadIndex.ConvertToProfileBufferIndex() +
+            ULEB128Size(reader.RemainingBytes()) + reader.RemainingBytes());
+      }
+      // Store the new end of buffer.
+      mNextWriteIndex =
+          ProfileBufferBlockIndex::CreateFromProfileBufferIndex(blockEnd);
+      mMaybeUnderlyingBuffer->mPushedBlockCount += 1;
+      // Finally, let aCallback write into the entry.
+      mMaybeUnderlyingBuffer->mBuffer.EntryWriterFromTo(maybeEntryWriter,
+                                                        blockIndex, blockEnd);
+      MOZ_ASSERT(maybeEntryWriter.isSome(),
+                 "Non-empty entry should always create an EntryWriter");
+      maybeEntryWriter->WriteULEB128(entryBytes);
+      MOZ_ASSERT(maybeEntryWriter->RemainingBytes() == entryBytes);
+    }
+
+#ifdef DEBUG
+    auto checkAllWritten = MakeScopeExit([&]() {
+      MOZ_ASSERT(!maybeEntryWriter || maybeEntryWriter->RemainingBytes() == 0);
+    });
+#endif  // DEBUG
+    return std::forward<Callback>(aCallback)(maybeEntryWriter);
+  }
+
+  // Add a new entry of known size, call `aCallback` with a pointer to a
+  // temporary ProfileBufferEntryWriter (can be null when out-of-session), and
+  // return whatever `aCallback` returns. Callback should not store the
+  // `ProfileBufferEntryWriter`, as it may become invalid after this thread-safe
+  // call.
+  template <typename Callback>
+  auto Put(Length aBytes, Callback&& aCallback) {
+    return ReserveAndPut([aBytes]() { return aBytes; },
+                         std::forward<Callback>(aCallback));
+  }
+
+  // Add a new entry copied from the given buffer, return block index.
+  ProfileBufferBlockIndex PutFrom(const void* aSrc, Length aBytes) {
+    return ReserveAndPut([aBytes]() { return aBytes; },
+                         [&](Maybe<ProfileBufferEntryWriter>& aEntryWriter) {
+                           if (MOZ_UNLIKELY(aEntryWriter.isNothing())) {
+                             // Out-of-session, return "empty" index.
+                             return ProfileBufferBlockIndex{};
+                           }
+                           aEntryWriter->WriteBytes(aSrc, aBytes);
+                           return aEntryWriter->CurrentBlockIndex();
+                         });
+  }
+
+  // Add a new single entry with *all* given object (using a Serializer for
+  // each), return block index.
+  template <typename... Ts>
+  ProfileBufferBlockIndex PutObjects(const Ts&... aTs) {
+    static_assert(sizeof...(Ts) > 0,
+                  "PutObjects must be given at least one object.");
+    return ReserveAndPut(
+        [&]() { return ProfileBufferEntryWriter::SumBytes(aTs...); },
+        [&](Maybe<ProfileBufferEntryWriter>& aEntryWriter) {
+          if (MOZ_UNLIKELY(aEntryWriter.isNothing())) {
+            // Out-of-session, return "empty" index.
+            return ProfileBufferBlockIndex{};
+          }
+          aEntryWriter->WriteObjects(aTs...);
+          return aEntryWriter->CurrentBlockIndex();
+        });
+  }
+
+  // Add a new entry copied from the given object, return block index.
+  template <typename T>
+  ProfileBufferBlockIndex PutObject(const T& aOb) {
+    return PutObjects(aOb);
+  }
+
+  // Append the contents of another BlocksRingBuffer to this one.
+  ProfileBufferBlockIndex AppendContents(const BlocksRingBuffer& aSrc) {
+    baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
+
+    if (MOZ_UNLIKELY(!mMaybeUnderlyingBuffer)) {
+      // We are out-of-session, could not append contents.
+      return ProfileBufferBlockIndex{};
+    }
+
+    baseprofiler::detail::BaseProfilerMaybeAutoLock srcLock(aSrc.mMutex);
+
+    if (MOZ_UNLIKELY(!aSrc.mMaybeUnderlyingBuffer)) {
+      // The other BRB is out-of-session, nothing to copy, we're done.
+      return ProfileBufferBlockIndex{};
+    }
+
+    const ProfileBufferIndex srcStartIndex =
+        aSrc.mFirstReadIndex.ConvertToProfileBufferIndex();
+    const ProfileBufferIndex srcEndIndex =
+        aSrc.mNextWriteIndex.ConvertToProfileBufferIndex();
+    const Length bytesToCopy = static_cast<Length>(srcEndIndex - srcStartIndex);
+
+    if (MOZ_UNLIKELY(bytesToCopy == 0)) {
+      // The other BRB is empty, nothing to copy, we're done.
+      return ProfileBufferBlockIndex{};
+    }
+
+    const Length bufferBytes =
+        mMaybeUnderlyingBuffer->mBuffer.BufferLength().Value();
+
+    MOZ_RELEASE_ASSERT(bytesToCopy <= bufferBytes,
+                       "Entry would wrap and overwrite itself");
+
+    // We will put all copied blocks at the end of the current buffer.
+    const ProfileBufferIndex dstStartIndex =
+        mNextWriteIndex.ConvertToProfileBufferIndex();
+    // Compute where the copy will end...
+    const ProfileBufferIndex dstEndIndex = dstStartIndex + bytesToCopy;
+
+    while (dstEndIndex >
+           mFirstReadIndex.ConvertToProfileBufferIndex() + bufferBytes) {
+      // About to trample on an old block.
+      ProfileBufferEntryReader reader = ReaderInBlockAt(mFirstReadIndex);
+      mMaybeUnderlyingBuffer->mClearedBlockCount += 1;
+      // Move the buffer reading start past this cleared block.
+      mFirstReadIndex = ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
+          mFirstReadIndex.ConvertToProfileBufferIndex() +
+          ULEB128Size(reader.RemainingBytes()) + reader.RemainingBytes());
+    }
+
+    // Store the new end of buffer.
+    mNextWriteIndex =
+        ProfileBufferBlockIndex::CreateFromProfileBufferIndex(dstEndIndex);
+    // Update our pushed count with the number of live blocks we are copying.
+    mMaybeUnderlyingBuffer->mPushedBlockCount +=
+        aSrc.mMaybeUnderlyingBuffer->mPushedBlockCount -
+        aSrc.mMaybeUnderlyingBuffer->mClearedBlockCount;
+
+    auto reader = aSrc.mMaybeUnderlyingBuffer->mBuffer.EntryReaderFromTo(
+        srcStartIndex, srcEndIndex, nullptr, nullptr);
+    auto writer = mMaybeUnderlyingBuffer->mBuffer.EntryWriterFromTo(
+        dstStartIndex, dstEndIndex);
+    writer.WriteFromReader(reader, bytesToCopy);
+
+    return ProfileBufferBlockIndex::CreateFromProfileBufferIndex(dstStartIndex);
+  }
+
+  // Clear all entries: Move read index to the end so that these entries cannot
+  // be read anymore.
+  void Clear() {
+    baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
+    ClearAllEntries();
+  }
+
+  // Clear all entries strictly before aBlockIndex, and move read index to the
+  // end so that these entries cannot be read anymore.
+  void ClearBefore(ProfileBufferBlockIndex aBlockIndex) {
+    baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
+    if (!mMaybeUnderlyingBuffer) {
+      return;
+    }
+    // Don't accept a not-yet-written index. One-past-the-end is ok.
+    MOZ_ASSERT(aBlockIndex <= mNextWriteIndex);
+    if (aBlockIndex <= mFirstReadIndex) {
+      // Already cleared.
+      return;
+    }
+    if (aBlockIndex == mNextWriteIndex) {
+      // Right past the end, just clear everything.
+      ClearAllEntries();
+      return;
+    }
+    // Otherwise we need to clear a subset of entries.
+    AssertBlockIndexIsValid(aBlockIndex);
+    // Just count skipped entries.
+    Reader reader(*this);
+    BlockIterator it = reader.begin();
+    for (; it.CurrentBlockIndex() < aBlockIndex; ++it) {
+      MOZ_ASSERT(it.CurrentBlockIndex() < reader.end().CurrentBlockIndex());
+      mMaybeUnderlyingBuffer->mClearedBlockCount += 1;
+    }
+    MOZ_ASSERT(it.CurrentBlockIndex() == aBlockIndex);
+    // Move read index to given index, so there's effectively no more entries
+    // before.
+    mFirstReadIndex = aBlockIndex;
+  }
+
+#ifdef DEBUG
+  void Dump() const {
+    baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
+    if (!mMaybeUnderlyingBuffer) {
+      printf("empty BlocksRingBuffer\n");
+      return;
+    }
+    using ULL = unsigned long long;
+    printf("start=%llu (%llu) end=%llu (%llu) - ",
+           ULL(mFirstReadIndex.ConvertToProfileBufferIndex()),
+           ULL(mFirstReadIndex.ConvertToProfileBufferIndex() &
+               (mMaybeUnderlyingBuffer->mBuffer.BufferLength().Value() - 1)),
+           ULL(mNextWriteIndex.ConvertToProfileBufferIndex()),
+           ULL(mNextWriteIndex.ConvertToProfileBufferIndex() &
+               (mMaybeUnderlyingBuffer->mBuffer.BufferLength().Value() - 1)));
+    mMaybeUnderlyingBuffer->mBuffer.Dump();
+  }
+#endif  // DEBUG
+
+ private:
+  // In DEBUG mode, assert that `aBlockIndex` is a valid index for a live block.
+  // (Not just in range, but points exactly at the start of a block.)
+  // Slow, so avoid it for internal checks; this is more to check what callers
+  // provide us.
+  void AssertBlockIndexIsValid(ProfileBufferBlockIndex aBlockIndex) const {
+#ifdef DEBUG
+    mMutex.AssertCurrentThreadOwns();
+    MOZ_ASSERT(aBlockIndex >= mFirstReadIndex);
+    MOZ_ASSERT(aBlockIndex < mNextWriteIndex);
+    // Quick check (default), or slow check (change '1' to '0') below:
+#  if 1
+    // Quick check that this looks like a valid block start.
+    // Read the entry size at the start of the block.
+    const Length entryBytes = ReaderInBlockAt(aBlockIndex).RemainingBytes();
+    MOZ_ASSERT(entryBytes > 0, "Empty entries are not allowed");
+    MOZ_ASSERT(
+        entryBytes < mMaybeUnderlyingBuffer->mBuffer.BufferLength().Value() -
+                         ULEB128Size(entryBytes),
+        "Entry would wrap and overwrite itself");
+    // The end of the block should be inside the live buffer range.
+    MOZ_ASSERT(aBlockIndex.ConvertToProfileBufferIndex() +
+                   ULEB128Size(entryBytes) + entryBytes <=
+               mNextWriteIndex.ConvertToProfileBufferIndex());
+#  else
+    // Slow check that the index is really the start of the block.
+    // This kills performances, as it reads from the first index until
+    // aBlockIndex. Only use to debug issues locally.
+    Reader reader(*this);
+    BlockIterator it = reader.begin();
+    for (; it.CurrentBlockIndex() < aBlockIndex; ++it) {
+      MOZ_ASSERT(it.CurrentBlockIndex() < reader.end().CurrentBlockIndex());
+    }
+    MOZ_ASSERT(it.CurrentBlockIndex() == aBlockIndex);
+#  endif
+#endif  // DEBUG
+  }
+
+  // In DEBUG mode, assert that `aBlockIndex` is a valid index for a live block,
+  // or is just past-the-end. (Not just in range, but points exactly at the
+  // start of a block.) Slow, so avoid it for internal checks; this is more to
+  // check what callers provide us.
+  void AssertBlockIndexIsValidOrEnd(ProfileBufferBlockIndex aBlockIndex) const {
+#ifdef DEBUG
+    mMutex.AssertCurrentThreadOwns();
+    if (aBlockIndex == mNextWriteIndex) {
+      return;
+    }
+    AssertBlockIndexIsValid(aBlockIndex);
+#endif  // DEBUG
+  }
+
+  // Create a reader for the block starting at aBlockIndex.
+  ProfileBufferEntryReader ReaderInBlockAt(
+      ProfileBufferBlockIndex aBlockIndex) const {
+    mMutex.AssertCurrentThreadOwns();
+    MOZ_ASSERT(mMaybeUnderlyingBuffer.isSome());
+    MOZ_ASSERT(aBlockIndex >= mFirstReadIndex);
+    MOZ_ASSERT(aBlockIndex < mNextWriteIndex);
+    // Create a reader from the given index until the end of the buffer.
+    ProfileBufferEntryReader reader =
+        mMaybeUnderlyingBuffer->mBuffer.EntryReaderFromTo(
+            aBlockIndex.ConvertToProfileBufferIndex(),
+            mNextWriteIndex.ConvertToProfileBufferIndex(), nullptr, nullptr);
+    // Read the block size at the beginning.
+    const Length entryBytes = reader.ReadULEB128<Length>();
+    // Make sure we don't overshoot the buffer.
+    MOZ_RELEASE_ASSERT(entryBytes <= reader.RemainingBytes());
+    ProfileBufferIndex nextBlockIndex =
+        aBlockIndex.ConvertToProfileBufferIndex() + ULEB128Size(entryBytes) +
+        entryBytes;
+    // And reduce the reader to the entry area. Only provide a next-block-index
+    // if it's not at the end of the buffer (i.e., there's an actual block
+    // there).
+    reader = mMaybeUnderlyingBuffer->mBuffer.EntryReaderFromTo(
+        aBlockIndex.ConvertToProfileBufferIndex() + ULEB128Size(entryBytes),
+        nextBlockIndex, aBlockIndex,
+        (nextBlockIndex < mNextWriteIndex.ConvertToProfileBufferIndex())
+            ? ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
+                  nextBlockIndex)
+            : ProfileBufferBlockIndex{});
+    return reader;
+  }
+
+  ProfileBufferEntryReader FullBufferReader() const {
+    mMutex.AssertCurrentThreadOwns();
+    if (!mMaybeUnderlyingBuffer) {
+      return {};
+    }
+    return mMaybeUnderlyingBuffer->mBuffer.EntryReaderFromTo(
+        mFirstReadIndex.ConvertToProfileBufferIndex(),
+        mNextWriteIndex.ConvertToProfileBufferIndex(), nullptr, nullptr);
+  }
+
+  // Clear all entries: Move read index to the end so that these entries cannot
+  // be read anymore.
+  void ClearAllEntries() {
+    mMutex.AssertCurrentThreadOwns();
+    if (!mMaybeUnderlyingBuffer) {
+      return;
+    }
+    // Mark all entries pushed so far as cleared.
+    mMaybeUnderlyingBuffer->mClearedBlockCount =
+        mMaybeUnderlyingBuffer->mPushedBlockCount;
+    // Move read index to write index, so there's effectively no more entries
+    // that can be read. (Not setting both to 0, in case user is keeping
+    // `ProfileBufferBlockIndex`'es to old entries.)
+    mFirstReadIndex = mNextWriteIndex;
+  }
+
+  // If there is an underlying buffer, clear all entries, and discard the
+  // buffer. This BlocksRingBuffer will now gracefully reject all API calls, and
+  // is in a state where a new underlying buffer may be set.
+  void ResetUnderlyingBuffer() {
+    mMutex.AssertCurrentThreadOwns();
+    if (!mMaybeUnderlyingBuffer) {
+      return;
+    }
+    ClearAllEntries();
+    mMaybeUnderlyingBuffer.reset();
+  }
+
+  // Used to de/serialize a BlocksRingBuffer (e.g., containing a backtrace).
+  friend ProfileBufferEntryWriter::Serializer<BlocksRingBuffer>;
+  friend ProfileBufferEntryReader::Deserializer<BlocksRingBuffer>;
+  friend ProfileBufferEntryWriter::Serializer<UniquePtr<BlocksRingBuffer>>;
+  friend ProfileBufferEntryReader::Deserializer<UniquePtr<BlocksRingBuffer>>;
+
+  // Mutex guarding the following members.
+  mutable baseprofiler::detail::BaseProfilerMaybeMutex mMutex;
+
+  struct UnderlyingBuffer {
+    // Create a buffer of the given length.
+    explicit UnderlyingBuffer(PowerOfTwo<Length> aLength) : mBuffer(aLength) {
+      MOZ_ASSERT(aLength.Value() > ULEB128MaxSize<Length>(),
+                 "Buffer should be able to contain more than a block size");
+    }
+
+    // Take ownership of an existing buffer.
+    UnderlyingBuffer(UniquePtr<Buffer::Byte[]> aExistingBuffer,
+                     PowerOfTwo<Length> aLength)
+        : mBuffer(std::move(aExistingBuffer), aLength) {
+      MOZ_ASSERT(aLength.Value() > ULEB128MaxSize<Length>(),
+                 "Buffer should be able to contain more than a block size");
+    }
+
+    // Use an externally-owned buffer.
+    UnderlyingBuffer(Buffer::Byte* aExternalBuffer, PowerOfTwo<Length> aLength)
+        : mBuffer(aExternalBuffer, aLength) {
+      MOZ_ASSERT(aLength.Value() > ULEB128MaxSize<Length>(),
+                 "Buffer should be able to contain more than a block size");
+    }
+
+    // Only allow move-construction.
+    UnderlyingBuffer(UnderlyingBuffer&&) = default;
+
+    // Copies and move-assignment are explictly disallowed.
+    UnderlyingBuffer(const UnderlyingBuffer&) = delete;
+    UnderlyingBuffer& operator=(const UnderlyingBuffer&) = delete;
+    UnderlyingBuffer& operator=(UnderlyingBuffer&&) = delete;
+
+    // Underlying circular byte buffer.
+    Buffer mBuffer;
+
+    // Statistics.
+    uint64_t mPushedBlockCount = 0;
+    uint64_t mClearedBlockCount = 0;
+  };
+
+  // Underlying buffer, with stats.
+  // Only valid during in-session period.
+  Maybe<UnderlyingBuffer> mMaybeUnderlyingBuffer;
+
+  // Index to the first block to be read (or cleared). Initialized to 1 because
+  // 0 is reserved for the "empty" ProfileBufferBlockIndex value. Kept between
+  // sessions, so that stored indices from one session will be gracefully denied
+  // in future sessions.
+  ProfileBufferBlockIndex mFirstReadIndex =
+      ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
+          ProfileBufferIndex(1));
+  // Index where the next new block should be allocated. Initialized to 1
+  // because 0 is reserved for the "empty" ProfileBufferBlockIndex value. Kept
+  // between sessions, so that stored indices from one session will be
+  // gracefully denied in future sessions.
+  ProfileBufferBlockIndex mNextWriteIndex =
+      ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
+          ProfileBufferIndex(1));
+};
+
+// ----------------------------------------------------------------------------
+// BlocksRingBuffer serialization
+
+// A BlocksRingBuffer can hide another one!
+// This will be used to store marker backtraces; They can be read back into a
+// UniquePtr<BlocksRingBuffer>.
+// Format: len (ULEB128) | start | end | buffer (len bytes) | pushed | cleared
+// len==0 marks an out-of-session buffer, or empty buffer.
+template <>
+struct ProfileBufferEntryWriter::Serializer<BlocksRingBuffer> {
+  static Length Bytes(const BlocksRingBuffer& aBuffer) {
+    baseprofiler::detail::BaseProfilerMaybeAutoLock lock(aBuffer.mMutex);
+    if (aBuffer.mMaybeUnderlyingBuffer.isNothing()) {
+      // Out-of-session, we only need 1 byte to store a length of 0.
+      return ULEB128Size<Length>(0);
+    }
+    const auto start = aBuffer.mFirstReadIndex.ConvertToProfileBufferIndex();
+    const auto end = aBuffer.mNextWriteIndex.ConvertToProfileBufferIndex();
+    const auto len = end - start;
+    if (len == 0) {
+      // In-session but empty, also store a length of 0.
+      return ULEB128Size<Length>(0);
+    }
+    return ULEB128Size(len) + sizeof(start) + sizeof(end) + len +
+           sizeof(aBuffer.mMaybeUnderlyingBuffer->mPushedBlockCount) +
+           sizeof(aBuffer.mMaybeUnderlyingBuffer->mClearedBlockCount);
+  }
+
+  static void Write(ProfileBufferEntryWriter& aEW,
+                    const BlocksRingBuffer& aBuffer) {
+    baseprofiler::detail::BaseProfilerMaybeAutoLock lock(aBuffer.mMutex);
+    if (aBuffer.mMaybeUnderlyingBuffer.isNothing()) {
+      // Out-of-session, only store a length of 0.
+      aEW.WriteULEB128<Length>(0);
+      return;
+    }
+    const auto start = aBuffer.mFirstReadIndex.ConvertToProfileBufferIndex();
+    const auto end = aBuffer.mNextWriteIndex.ConvertToProfileBufferIndex();
+    MOZ_ASSERT(end - start <= std::numeric_limits<Length>::max());
+    const auto len = static_cast<Length>(end - start);
+    if (len == 0) {
+      // In-session but empty, only store a length of 0.
+      aEW.WriteULEB128<Length>(0);
+      return;
+    }
+    // In-session.
+    // Store buffer length, start and end indices.
+    aEW.WriteULEB128<Length>(len);
+    aEW.WriteObject(start);
+    aEW.WriteObject(end);
+    // Write all the bytes.
+    auto reader = aBuffer.FullBufferReader();
+    aEW.WriteFromReader(reader, reader.RemainingBytes());
+    // And write stats.
+    aEW.WriteObject(aBuffer.mMaybeUnderlyingBuffer->mPushedBlockCount);
+    aEW.WriteObject(aBuffer.mMaybeUnderlyingBuffer->mClearedBlockCount);
+  }
+};
+
+// A serialized BlocksRingBuffer can be read into an empty buffer (either
+// out-of-session, or in-session with enough room).
+template <>
+struct ProfileBufferEntryReader::Deserializer<BlocksRingBuffer> {
+  static void ReadInto(ProfileBufferEntryReader& aER,
+                       BlocksRingBuffer& aBuffer) {
+    // Expect an empty buffer, as we're going to overwrite it.
+    MOZ_ASSERT(aBuffer.GetState().mRangeStart == aBuffer.GetState().mRangeEnd);
+    // Read the stored buffer length.
+    const auto len = aER.ReadULEB128<Length>();
+    if (len == 0) {
+      // 0-length means an "uninteresting" buffer, just return now.
+      return;
+    }
+    // We have a non-empty buffer to read.
+    if (aBuffer.BufferLength().isSome()) {
+      // Output buffer is in-session (i.e., it already has a memory buffer
+      // attached). Make sure the caller allocated enough space.
+      MOZ_RELEASE_ASSERT(aBuffer.BufferLength()->Value() >= len);
+    } else {
+      // Output buffer is out-of-session, attach a new memory buffer.
+      aBuffer.Set(PowerOfTwo<Length>(len));
+      MOZ_ASSERT(aBuffer.BufferLength()->Value() >= len);
+    }
+    // Read start and end indices.
+    const auto start = aER.ReadObject<ProfileBufferIndex>();
+    aBuffer.mFirstReadIndex =
+        ProfileBufferBlockIndex::CreateFromProfileBufferIndex(start);
+    const auto end = aER.ReadObject<ProfileBufferIndex>();
+    aBuffer.mNextWriteIndex =
+        ProfileBufferBlockIndex::CreateFromProfileBufferIndex(end);
+    MOZ_ASSERT(end - start == len);
+    // Copy bytes into the buffer.
+    auto writer =
+        aBuffer.mMaybeUnderlyingBuffer->mBuffer.EntryWriterFromTo(start, end);
+    writer.WriteFromReader(aER, end - start);
+    MOZ_ASSERT(writer.RemainingBytes() == 0);
+    // Finally copy stats.
+    aBuffer.mMaybeUnderlyingBuffer->mPushedBlockCount = aER.ReadObject<
+        decltype(aBuffer.mMaybeUnderlyingBuffer->mPushedBlockCount)>();
+    aBuffer.mMaybeUnderlyingBuffer->mClearedBlockCount = aER.ReadObject<
+        decltype(aBuffer.mMaybeUnderlyingBuffer->mClearedBlockCount)>();
+  }
+
+  // We cannot output a BlocksRingBuffer object (not copyable), use `ReadInto()`
+  // or `aER.ReadObject<UniquePtr<BlocksRinbBuffer>>()` instead.
+  static BlocksRingBuffer Read(ProfileBufferEntryReader& aER) = delete;
+};
+
+// A BlocksRingBuffer is usually refererenced through a UniquePtr, for
+// convenience we support (de)serializing that UniquePtr directly.
+// This is compatible with the non-UniquePtr serialization above, with a null
+// pointer being treated like an out-of-session or empty buffer; and any of
+// these would be deserialized into a null pointer.
+template <>
+struct ProfileBufferEntryWriter::Serializer<UniquePtr<BlocksRingBuffer>> {
+  static Length Bytes(const UniquePtr<BlocksRingBuffer>& aBufferUPtr) {
+    if (!aBufferUPtr) {
+      // Null pointer, treat it like an empty buffer, i.e., write length of 0.
+      return ULEB128Size<Length>(0);
+    }
+    // Otherwise write the pointed-at BlocksRingBuffer (which could be
+    // out-of-session or empty.)
+    return SumBytes(*aBufferUPtr);
+  }
+
+  static void Write(ProfileBufferEntryWriter& aEW,
+                    const UniquePtr<BlocksRingBuffer>& aBufferUPtr) {
+    if (!aBufferUPtr) {
+      // Null pointer, treat it like an empty buffer, i.e., write length of 0.
+      aEW.WriteULEB128<Length>(0);
+      return;
+    }
+    // Otherwise write the pointed-at BlocksRingBuffer (which could be
+    // out-of-session or empty.)
+    aEW.WriteObject(*aBufferUPtr);
+  }
+};
+
+template <>
+struct ProfileBufferEntryReader::Deserializer<UniquePtr<BlocksRingBuffer>> {
+  static void ReadInto(ProfileBufferEntryReader& aER,
+                       UniquePtr<BlocksRingBuffer>& aBuffer) {
+    aBuffer = Read(aER);
+  }
+
+  static UniquePtr<BlocksRingBuffer> Read(ProfileBufferEntryReader& aER) {
+    UniquePtr<BlocksRingBuffer> bufferUPtr;
+    // Keep a copy of the reader before reading the length, so we can restart
+    // from here below.
+    ProfileBufferEntryReader readerBeforeLen = aER;
+    // Read the stored buffer length.
+    const auto len = aER.ReadULEB128<Length>();
+    if (len == 0) {
+      // 0-length means an "uninteresting" buffer, just return nullptr.
+      return bufferUPtr;
+    }
+    // We have a non-empty buffer.
+    // allocate an empty BlocksRingBuffer without mutex.
+    bufferUPtr = MakeUnique<BlocksRingBuffer>(
+        BlocksRingBuffer::ThreadSafety::WithoutMutex);
+    // Rewind the reader before the length and deserialize the contents, using
+    // the non-UniquePtr Deserializer.
+    aER = readerBeforeLen;
+    aER.ReadIntoObject(*bufferUPtr);
+    return bufferUPtr;
+  }
+};
+
+}  // namespace mozilla
+
+#endif  // BlocksRingBuffer_h