tor-browser

ProfileChunkedBuffer.h (63088B)

---

/* -*- 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 ProfileChunkedBuffer_h
#define ProfileChunkedBuffer_h

#include "mozilla/Attributes.h"
#include "mozilla/BaseProfilerDetail.h"
#include "mozilla/NotNull.h"
#include "mozilla/ProfileBufferChunkManager.h"
#include "mozilla/ProfileBufferChunkManagerSingle.h"
#include "mozilla/ProfileBufferEntrySerialization.h"
#include "mozilla/ProfileChunkedBufferDetail.h"
#include "mozilla/RefPtr.h"
#include "mozilla/ScopeExit.h"

#include <utility>

#ifdef DEBUG
#  include <cstdio>
#endif

namespace mozilla {

// Thread-safe buffer that can store blocks of different sizes during defined
// sessions, using Chunks (from a ChunkManager) as storage.
//
// Each *block* contains an *entry* and the entry size:
// [ entry_size | entry ] [ entry_size | entry ] ...
//
// *In-session* is a period of time during which `ProfileChunkedBuffer` allows
// reading and writing.
// *Out-of-session*, the `ProfileChunkedBuffer` 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 a ProfileBufferEntryWriter. E.g.:
// ```
// ProfileChunkedBuffer cb(...);
// cb.ReserveAndPut([]() { return sizeof(123); },
//                  [&](Maybe<ProfileBufferEntryWriter>& aEW) {
//                    if (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
// chunk memory and therefore should not live longer.
// Different type of objects may be serialized into an entry, see
// `ProfileBufferEntryWriter::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.:
// ```
// cb.ReadEach([](ProfileBufferEntryReader& aER) {
//   /* Use ProfileBufferEntryReader functions to read serialized objects. */
//   int n = aER.ReadObject<int>();
// });
// ```
// Different type of objects may be deserialized from an entry, see
// `ProfileBufferEntryReader::Deserializer` for more information.
//
// Writers may retrieve the block index corresponding to an entry
// (`ProfileBufferBlockIndex` is an opaque type preventing the user from easily
// modifying it). That index may later be used with `ReadAt` to get back to the
// entry in that particular block -- if it still exists.
class ProfileChunkedBuffer {
public:
 using Byte = ProfileBufferChunk::Byte;
 using Length = ProfileBufferChunk::Length;

 enum class ThreadSafety { WithoutMutex, WithMutex };

 // Default constructor starts out-of-session (nothing to read or write).
 explicit ProfileChunkedBuffer(ThreadSafety aThreadSafety)
     : mMutex(aThreadSafety != ThreadSafety::WithoutMutex) {}

 // Start in-session with external chunk manager.
 ProfileChunkedBuffer(ThreadSafety aThreadSafety,
                      ProfileBufferChunkManager& aChunkManager)
     : mMutex(aThreadSafety != ThreadSafety::WithoutMutex) {
   SetChunkManager(aChunkManager);
 }

 // Start in-session with owned chunk manager.
 ProfileChunkedBuffer(ThreadSafety aThreadSafety,
                      UniquePtr<ProfileBufferChunkManager>&& aChunkManager)
     : mMutex(aThreadSafety != ThreadSafety::WithoutMutex) {
   SetChunkManager(std::move(aChunkManager));
 }

 ~ProfileChunkedBuffer() {
   // Do proper clean-up by resetting the chunk manager.
   ResetChunkManager();
 }

 // This cannot change during the lifetime of this buffer, so there's no need
 // to lock.
 [[nodiscard]] bool IsThreadSafe() const { return mMutex.IsActivated(); }

 [[nodiscard]] bool IsInSession() const {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   return !!mChunkManager;
 }

 // Stop using the current chunk manager.
 // If we own the current chunk manager, it will be destroyed.
 // This will always clear currently-held chunks, if any.
 void ResetChunkManager() {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   (void)ResetChunkManager(lock);
 }

 // Set the current chunk manager.
 // The caller is responsible for keeping the chunk manager alive as along as
 // it's used here (until the next (Re)SetChunkManager, or
 // ~ProfileChunkedBuffer).
 void SetChunkManager(ProfileBufferChunkManager& aChunkManager) {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   (void)ResetChunkManager(lock);
   SetChunkManager(aChunkManager, lock);
 }

 // Set the current chunk manager, and keep ownership of it.
 void SetChunkManager(UniquePtr<ProfileBufferChunkManager>&& aChunkManager) {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   (void)ResetChunkManager(lock);
   mOwnedChunkManager = std::move(aChunkManager);
   if (mOwnedChunkManager) {
     SetChunkManager(*mOwnedChunkManager, lock);
   }
 }

 // Set the current chunk manager, except if it's already the one provided.
 // The caller is responsible for keeping the chunk manager alive as along as
 // it's used here (until the next (Re)SetChunkManager, or
 // ~ProfileChunkedBuffer).
 void SetChunkManagerIfDifferent(ProfileBufferChunkManager& aChunkManager) {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   if (!mChunkManager || mChunkManager != &aChunkManager) {
     (void)ResetChunkManager(lock);
     SetChunkManager(aChunkManager, lock);
   }
 }

 // Clear the contents of this buffer, ready to receive new chunks.
 // Note that memory is not freed: No chunks are destroyed, they are all
 // receycled.
 // Also the range doesn't reset, instead it continues at some point after the
 // previous range. This may be useful if the caller may be keeping indexes
 // into old chunks that have now been cleared, using these indexes will fail
 // gracefully (instead of potentially pointing into new data).
 void Clear() {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   if (MOZ_UNLIKELY(!mChunkManager)) {
     // Out-of-session.
     return;
   }

   mRangeStart = mRangeEnd = mNextChunkRangeStart;
   mPushedBlockCount = 0;
   mClearedBlockCount = 0;
   mFailedPutBytes = 0;

   // Recycle all released chunks as "next" chunks. This will reduce the number
   // of future allocations. Also, when using ProfileBufferChunkManagerSingle,
   // this retrieves the one chunk if it was released.
   UniquePtr<ProfileBufferChunk> releasedChunks =
       mChunkManager->GetExtantReleasedChunks();
   if (releasedChunks) {
     // Released chunks should be in the "Done" state, they need to be marked
     // "recycled" before they can be reused.
     for (ProfileBufferChunk* chunk = releasedChunks.get(); chunk;
          chunk = chunk->GetNext()) {
       chunk->MarkRecycled();
     }
     mNextChunks = ProfileBufferChunk::Join(std::move(mNextChunks),
                                            std::move(releasedChunks));
   }

   if (mCurrentChunk) {
     // We already have a current chunk (empty or in-use), mark it "done" and
     // then "recycled", ready to be reused.
     mCurrentChunk->MarkDone();
     mCurrentChunk->MarkRecycled();
   } else {
     if (!mNextChunks) {
       // No current chunk, and no next chunks to recycle, nothing more to do.
       // The next "Put" operation will try to allocate a chunk as needed.
       return;
     }

     // No current chunk, take a next chunk.
     mCurrentChunk = std::exchange(mNextChunks, mNextChunks->ReleaseNext());
   }

   // Here, there was already a current chunk, or one has just been taken.
   // Make sure it's ready to receive new entries.
   InitializeCurrentChunk(lock);
 }

 // Buffer maximum length in bytes.
 Maybe<size_t> BufferLength() const {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   if (!mChunkManager) {
     return Nothing{};
   }
   return Some(mChunkManager->MaxTotalSize());
 }

 [[nodiscard]] size_t SizeOfExcludingThis(MallocSizeOf aMallocSizeOf) const {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   return SizeOfExcludingThis(aMallocSizeOf, lock);
 }

 [[nodiscard]] size_t SizeOfIncludingThis(MallocSizeOf aMallocSizeOf) const {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   return aMallocSizeOf(this) + SizeOfExcludingThis(aMallocSizeOf, lock);
 }

 // Snapshot of the buffer state.
 struct State {
   // Index to/before the first block.
   ProfileBufferIndex mRangeStart = 1;

   // Index past the last block. Equals mRangeStart if empty.
   ProfileBufferIndex mRangeEnd = 1;

   // 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;

   // Number of bytes that could not be put into this buffer.
   uint64_t mFailedPutBytes = 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.
 [[nodiscard]] State GetState() const {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   return {mRangeStart, mRangeEnd, mPushedBlockCount, mClearedBlockCount,
           mFailedPutBytes};
 }

 // In in-session, return the start TimeStamp of the earliest chunk.
 // If out-of-session, return a null TimeStamp.
 [[nodiscard]] TimeStamp GetEarliestChunkStartTimeStamp() const {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   if (MOZ_UNLIKELY(!mChunkManager)) {
     // Out-of-session.
     return {};
   }
   return mChunkManager->PeekExtantReleasedChunks(
       [&](const ProfileBufferChunk* aOldestChunk) -> TimeStamp {
         if (aOldestChunk) {
           return aOldestChunk->ChunkHeader().mStartTimeStamp;
         }
         if (mCurrentChunk) {
           return mCurrentChunk->ChunkHeader().mStartTimeStamp;
         }
         return {};
       });
 }

 [[nodiscard]] bool IsEmpty() const {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   return mRangeStart == mRangeEnd;
 }

 // True if this buffer is already locked on this thread.
 // This should be used if some functions may call an already-locked buffer,
 // e.g.: Put -> memory hook -> profiler_add_native_allocation_marker -> Put.
 [[nodiscard]] bool IsThreadSafeAndLockedOnCurrentThread() const {
   return mMutex.IsActivatedAndLockedOnCurrentThread();
 }

 // 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)();
 }

 // Reserve a block that can hold an entry of the given `aCallbackEntryBytes()`
 // size, write the entry size (ULEB128-encoded), and invoke and return
 // `aCallback(Maybe<ProfileBufferEntryWriter>&)`.
 // Note: `aCallbackEntryBytes` 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 CallbackEntryBytes, typename Callback>
 auto ReserveAndPut(CallbackEntryBytes&& aCallbackEntryBytes,
                    Callback&& aCallback)
     -> decltype(std::forward<Callback>(aCallback)(
         std::declval<Maybe<ProfileBufferEntryWriter>&>())) {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);

   // This can only be read in the 2nd lambda below after it has been written
   // by the first lambda.
   Length entryBytes;

   return ReserveAndPutRaw(
       [&]() {
         entryBytes = std::forward<CallbackEntryBytes>(aCallbackEntryBytes)();
         MOZ_ASSERT(entryBytes != 0, "Empty entries are not allowed");
         return ULEB128Size(entryBytes) + entryBytes;
       },
       [&](Maybe<ProfileBufferEntryWriter>& aMaybeEntryWriter) {
         if (aMaybeEntryWriter.isSome()) {
           aMaybeEntryWriter->WriteULEB128(entryBytes);
           MOZ_ASSERT(aMaybeEntryWriter->RemainingBytes() == entryBytes);
         }
         return std::forward<Callback>(aCallback)(aMaybeEntryWriter);
       },
       lock);
 }

 template <typename Callback>
 auto Put(Length aEntryBytes, Callback&& aCallback) {
   return ReserveAndPut([aEntryBytes]() { return aEntryBytes; },
                        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; },
       [aSrc, aBytes](Maybe<ProfileBufferEntryWriter>& aMaybeEntryWriter) {
         if (aMaybeEntryWriter.isNothing()) {
           return ProfileBufferBlockIndex{};
         }
         aMaybeEntryWriter->WriteBytes(aSrc, aBytes);
         return aMaybeEntryWriter->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>& aMaybeEntryWriter) {
         if (aMaybeEntryWriter.isNothing()) {
           return ProfileBufferBlockIndex{};
         }
         aMaybeEntryWriter->WriteObjects(aTs...);
         return aMaybeEntryWriter->CurrentBlockIndex();
       });
 }

 // Add a new entry copied from the given object, return block index.
 template <typename T>
 ProfileBufferBlockIndex PutObject(const T& aOb) {
   return PutObjects(aOb);
 }

 // Get *all* chunks related to this buffer, including extant chunks in its
 // ChunkManager, and yet-unused new/recycled chunks.
 // We don't expect this buffer to be used again, though it's still possible
 // and will allocate the first buffer when needed.
 [[nodiscard]] UniquePtr<ProfileBufferChunk> GetAllChunks() {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   if (MOZ_UNLIKELY(!mChunkManager)) {
     // Out-of-session.
     return nullptr;
   }
   UniquePtr<ProfileBufferChunk> chunks =
       mChunkManager->GetExtantReleasedChunks();
   (void)HandleRequestedChunk_IsPending(lock);
   if (MOZ_LIKELY(!!mCurrentChunk)) {
     mCurrentChunk->MarkDone();
     chunks =
         ProfileBufferChunk::Join(std::move(chunks), std::move(mCurrentChunk));
   }
   chunks =
       ProfileBufferChunk::Join(std::move(chunks), std::move(mNextChunks));
   mChunkManager->ForgetUnreleasedChunks();
   mRangeStart = mRangeEnd = mNextChunkRangeStart;
   return chunks;
 }

 // True if the given index points inside the current chunk (up to the last
 // written byte).
 // This could be used to check if an index written now would have a good
 // chance of referring to a previous block that has not been destroyed yet.
 // But use with extreme care: This information may become incorrect right
 // after this function returns, because new writes could start a new chunk.
 [[nodiscard]] bool IsIndexInCurrentChunk(ProfileBufferIndex aIndex) const {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   if (MOZ_UNLIKELY(!mChunkManager || !mCurrentChunk)) {
     // Out-of-session, or no current chunk.
     return false;
   }
   return (mCurrentChunk->RangeStart() <= aIndex) &&
          (aIndex < (mCurrentChunk->RangeStart() +
                     mCurrentChunk->OffsetPastLastBlock()));
 }

 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.
     mBuffer->mMutex.AssertCurrentThreadOwns();
   }
#endif  // DEBUG

   // Comparison with other iterator, mostly used in range-for loops.
   [[nodiscard]] bool operator==(const BlockIterator& aRhs) const {
     MOZ_ASSERT(mBuffer == aRhs.mBuffer);
     return mCurrentBlockIndex == aRhs.mCurrentBlockIndex;
   }
   [[nodiscard]] bool operator!=(const BlockIterator& aRhs) const {
     MOZ_ASSERT(mBuffer == aRhs.mBuffer);
     return mCurrentBlockIndex != aRhs.mCurrentBlockIndex;
   }

   // Advance to next BlockIterator.
   BlockIterator& operator++() {
     mBuffer->mMutex.AssertCurrentThreadOwns();
     mCurrentBlockIndex =
         ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
             mNextBlockPointer.GlobalRangePosition());
     mCurrentEntry =
         mNextBlockPointer.EntryReader(mNextBlockPointer.ReadEntrySize());
     return *this;
   }

   // Dereferencing creates a `ProfileBufferEntryReader` object for the entry
   // inside this block.
   // (Note: It would be possible to return a `const
   // ProfileBufferEntryReader&`, but not useful in practice, because in most
   // case the user will want to read, which is non-const.)
   [[nodiscard]] ProfileBufferEntryReader operator*() const {
     return mCurrentEntry;
   }

   // True if this iterator is just past the last entry.
   [[nodiscard]] bool IsAtEnd() const {
     return mCurrentEntry.RemainingBytes() == 0;
   }

   // Can be used as reference to come back to this entry with `GetEntryAt()`.
   [[nodiscard]] ProfileBufferBlockIndex CurrentBlockIndex() const {
     return mCurrentBlockIndex;
   }

   // Index past the end of this block, which is the start of the next block.
   [[nodiscard]] ProfileBufferBlockIndex NextBlockIndex() const {
     MOZ_ASSERT(!IsAtEnd());
     return ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
         mNextBlockPointer.GlobalRangePosition());
   }

   // Index of the first block in the whole buffer.
   [[nodiscard]] ProfileBufferBlockIndex BufferRangeStart() const {
     mBuffer->mMutex.AssertCurrentThreadOwns();
     return ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
         mBuffer->mRangeStart);
   }

   // Index past the last block in the whole buffer.
   [[nodiscard]] ProfileBufferBlockIndex BufferRangeEnd() const {
     mBuffer->mMutex.AssertCurrentThreadOwns();
     return ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
         mBuffer->mRangeEnd);
   }

  private:
   // Only a Reader can instantiate a BlockIterator.
   friend class Reader;

   BlockIterator(const ProfileChunkedBuffer& aBuffer,
                 const ProfileBufferChunk* aChunks0,
                 const ProfileBufferChunk* aChunks1,
                 ProfileBufferBlockIndex aBlockIndex)
       : mNextBlockPointer(aChunks0, aChunks1, aBlockIndex),
         mCurrentBlockIndex(
             ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
                 mNextBlockPointer.GlobalRangePosition())),
         mCurrentEntry(
             mNextBlockPointer.EntryReader(mNextBlockPointer.ReadEntrySize())),
         mBuffer(WrapNotNull(&aBuffer)) {
     // No BlockIterator should live outside of a mutexed call.
     mBuffer->mMutex.AssertCurrentThreadOwns();
   }

   profiler::detail::InChunkPointer mNextBlockPointer;

   ProfileBufferBlockIndex mCurrentBlockIndex;

   ProfileBufferEntryReader mCurrentEntry;

   // Using a non-null pointer instead of a reference, to allow copying.
   // This BlockIterator should only live inside one of the thread-safe
   // ProfileChunkedBuffer functions, for this reference to stay valid.
   NotNull<const ProfileChunkedBuffer*> mBuffer;
 };

 // 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.
     mBuffer.mMutex.AssertCurrentThreadOwns();
   }
#endif  // DEBUG

   // Index of the first block in the whole buffer.
   [[nodiscard]] ProfileBufferBlockIndex BufferRangeStart() const {
     mBuffer.mMutex.AssertCurrentThreadOwns();
     return ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
         mBuffer.mRangeStart);
   }

   // Index past the last block in the whole buffer.
   [[nodiscard]] ProfileBufferBlockIndex BufferRangeEnd() const {
     mBuffer.mMutex.AssertCurrentThreadOwns();
     return ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
         mBuffer.mRangeEnd);
   }

   // Iterators to the first and past-the-last blocks.
   // Compatible with range-for (see `ForEach` below as example).
   [[nodiscard]] BlockIterator begin() const {
     return BlockIterator(mBuffer, mChunks0, mChunks1, nullptr);
   }
   // Note that a `BlockIterator` at the `end()` should not be dereferenced, as
   // there is no actual block there!
   [[nodiscard]] BlockIterator end() const {
     return BlockIterator(mBuffer, nullptr, nullptr, nullptr);
   }

   // 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!
   [[nodiscard]] 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.)
     return BlockIterator(mBuffer, mChunks0, mChunks1, 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);
     }
   }

   // If this reader only points at one chunk with some data, this data will be
   // exposed as a single entry.
   [[nodiscard]] ProfileBufferEntryReader SingleChunkDataAsEntry() {
     const ProfileBufferChunk* onlyNonEmptyChunk = nullptr;
     for (const ProfileBufferChunk* chunkList : {mChunks0, mChunks1}) {
       for (const ProfileBufferChunk* chunk = chunkList; chunk;
            chunk = chunk->GetNext()) {
         if (chunk->OffsetFirstBlock() != chunk->OffsetPastLastBlock()) {
           if (onlyNonEmptyChunk) {
             // More than one non-empty chunk.
             return ProfileBufferEntryReader();
           }
           onlyNonEmptyChunk = chunk;
         }
       }
     }
     if (!onlyNonEmptyChunk) {
       // No non-empty chunks.
       return ProfileBufferEntryReader();
     }
     // Here, we have found one chunk that had some data.
     return ProfileBufferEntryReader(
         onlyNonEmptyChunk->BufferSpan().FromTo(
             onlyNonEmptyChunk->OffsetFirstBlock(),
             onlyNonEmptyChunk->OffsetPastLastBlock()),
         ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
             onlyNonEmptyChunk->RangeStart()),
         ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
             onlyNonEmptyChunk->RangeStart() +
             (onlyNonEmptyChunk->OffsetPastLastBlock() -
              onlyNonEmptyChunk->OffsetFirstBlock())));
   }

  private:
   friend class ProfileChunkedBuffer;

   explicit Reader(const ProfileChunkedBuffer& aBuffer,
                   const ProfileBufferChunk* aChunks0,
                   const ProfileBufferChunk* aChunks1)
       : mBuffer(aBuffer), mChunks0(aChunks0), mChunks1(aChunks1) {
     // No Reader should live outside of a mutexed call.
     mBuffer.mMutex.AssertCurrentThreadOwns();
   }

   // This Reader should only live inside one of the thread-safe
   // ProfileChunkedBuffer functions, for this reference to stay valid.
   const ProfileChunkedBuffer& mBuffer;
   const ProfileBufferChunk* mChunks0;
   const ProfileBufferChunk* mChunks1;
 };

 // In in-session, call `aCallback(ProfileChunkedBuffer::Reader&)` and return
 // true. Callback should not store `Reader`, because it may become invalid
 // after this call.
 // If out-of-session, return false (callback is not invoked).
 template <typename Callback>
 [[nodiscard]] auto Read(Callback&& aCallback) const {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   if (MOZ_UNLIKELY(!mChunkManager)) {
     // Out-of-session.
     return std::forward<Callback>(aCallback)(static_cast<Reader*>(nullptr));
   }
   return mChunkManager->PeekExtantReleasedChunks(
       [&](const ProfileBufferChunk* aOldestChunk) {
         Reader reader(*this, aOldestChunk, mCurrentChunk.get());
         return std::forward<Callback>(aCallback)(&reader);
       });
 }

 // Invoke `aCallback(ProfileBufferEntryReader& [, ProfileBufferBlockIndex])`
 // on each entry, it must read or at least skip everything. Either/both chunk
 // pointers may be null.
 template <typename Callback>
 static void ReadEach(const ProfileBufferChunk* aChunks0,
                      const ProfileBufferChunk* aChunks1,
                      Callback&& aCallback) {
   static_assert(std::is_invocable_v<Callback, ProfileBufferEntryReader&> ||
                     std::is_invocable_v<Callback, ProfileBufferEntryReader&,
                                         ProfileBufferBlockIndex>,
                 "ReadEach callback must take ProfileBufferEntryReader& and "
                 "optionally a ProfileBufferBlockIndex");
   profiler::detail::InChunkPointer p{aChunks0, aChunks1};
   while (!p.IsNull()) {
     // The position right before an entry size *is* a block index.
     const ProfileBufferBlockIndex blockIndex =
         ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
             p.GlobalRangePosition());
     Length entrySize = p.ReadEntrySize();
     if (entrySize == 0) {
       return;
     }
     ProfileBufferEntryReader entryReader = p.EntryReader(entrySize);
     if (entryReader.RemainingBytes() == 0) {
       return;
     }
     MOZ_ASSERT(entryReader.RemainingBytes() == entrySize);
     if constexpr (std::is_invocable_v<Callback, ProfileBufferEntryReader&,
                                       ProfileBufferBlockIndex>) {
       aCallback(entryReader, blockIndex);
     } else {
       (void)blockIndex;
       aCallback(entryReader);
     }
     MOZ_ASSERT(entryReader.RemainingBytes() == 0);
   }
 }

 // Invoke `aCallback(ProfileBufferEntryReader& [, ProfileBufferBlockIndex])`
 // on each entry, it must read or at least skip everything.
 template <typename Callback>
 void ReadEach(Callback&& aCallback) const {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   if (MOZ_UNLIKELY(!mChunkManager)) {
     // Out-of-session.
     return;
   }
   mChunkManager->PeekExtantReleasedChunks(
       [&](const ProfileBufferChunk* aOldestChunk) {
         ReadEach(aOldestChunk, mCurrentChunk.get(),
                  std::forward<Callback>(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.
 // Either/both chunk pointers may be null.
 template <typename Callback>
 [[nodiscard]] static auto ReadAt(ProfileBufferBlockIndex aMinimumBlockIndex,
                                  const ProfileBufferChunk* aChunks0,
                                  const ProfileBufferChunk* aChunks1,
                                  Callback&& aCallback) {
   static_assert(
       std::is_invocable_v<Callback, Maybe<ProfileBufferEntryReader>&&>,
       "ReadAt callback must take a Maybe<ProfileBufferEntryReader>&&");
   Maybe<ProfileBufferEntryReader> maybeEntryReader;
   if (profiler::detail::InChunkPointer p{aChunks0, aChunks1}; !p.IsNull()) {
     // If the pointer position is before the given position, try to advance.
     if (p.GlobalRangePosition() >=
             aMinimumBlockIndex.ConvertToProfileBufferIndex() ||
         p.AdvanceToGlobalRangePosition(
             aMinimumBlockIndex.ConvertToProfileBufferIndex())) {
       MOZ_ASSERT(p.GlobalRangePosition() >=
                  aMinimumBlockIndex.ConvertToProfileBufferIndex());
       // Here we're pointing at the start of a block, try to read the entry
       // size. (Entries cannot be empty, so 0 means failure.)
       if (Length entrySize = p.ReadEntrySize(); entrySize != 0) {
         maybeEntryReader.emplace(p.EntryReader(entrySize));
         if (maybeEntryReader->RemainingBytes() == 0) {
           // An empty entry reader means there was no complete block at the
           // given index.
           maybeEntryReader.reset();
         } else {
           MOZ_ASSERT(maybeEntryReader->RemainingBytes() == entrySize);
         }
       }
     }
   }
#ifdef DEBUG
   auto assertAllRead = MakeScopeExit([&]() {
     MOZ_ASSERT(!maybeEntryReader || maybeEntryReader->RemainingBytes() == 0);
   });
#endif  // DEBUG
   return std::forward<Callback>(aCallback)(std::move(maybeEntryReader));
 }

 // 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>
 [[nodiscard]] auto ReadAt(ProfileBufferBlockIndex aBlockIndex,
                           Callback&& aCallback) const {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   if (MOZ_UNLIKELY(!mChunkManager)) {
     // Out-of-session.
     return std::forward<Callback>(aCallback)(Nothing{});
   }
   return mChunkManager->PeekExtantReleasedChunks(
       [&](const ProfileBufferChunk* aOldestChunk) {
         return ReadAt(aBlockIndex, aOldestChunk, mCurrentChunk.get(),
                       std::forward<Callback>(aCallback));
       });
 }

 // Append the contents of another ProfileChunkedBuffer to this one.
 ProfileBufferBlockIndex AppendContents(const ProfileChunkedBuffer& aSrc) {
   ProfileBufferBlockIndex firstBlockIndex;
   // If we start failing, we'll stop writing.
   bool failed = false;
   aSrc.ReadEach([&](ProfileBufferEntryReader& aER) {
     if (failed) {
       return;
     }
     failed =
         !Put(aER.RemainingBytes(), [&](Maybe<ProfileBufferEntryWriter>& aEW) {
           if (aEW.isNothing()) {
             return false;
           }
           if (!firstBlockIndex) {
             firstBlockIndex = aEW->CurrentBlockIndex();
           }
           aEW->WriteFromReader(aER, aER.RemainingBytes());
           return true;
         });
   });
   return failed ? nullptr : firstBlockIndex;
 }

#ifdef DEBUG
 void Dump(std::FILE* aFile = stdout) const {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   fprintf(aFile,
           "ProfileChunkedBuffer[%p] State: range %u-%u pushed=%u cleared=%u "
           "(live=%u) failed-puts=%u bytes",
           this, unsigned(mRangeStart), unsigned(mRangeEnd),
           unsigned(mPushedBlockCount), unsigned(mClearedBlockCount),
           unsigned(mPushedBlockCount) - unsigned(mClearedBlockCount),
           unsigned(mFailedPutBytes));
   if (MOZ_UNLIKELY(!mChunkManager)) {
     fprintf(aFile, " - Out-of-session\n");
     return;
   }
   fprintf(aFile, " - chunks:\n");
   bool hasChunks = false;
   mChunkManager->PeekExtantReleasedChunks(
       [&](const ProfileBufferChunk* aOldestChunk) {
         for (const ProfileBufferChunk* chunk = aOldestChunk; chunk;
              chunk = chunk->GetNext()) {
           fprintf(aFile, "R ");
           chunk->Dump(aFile);
           hasChunks = true;
         }
       });
   if (mCurrentChunk) {
     fprintf(aFile, "C ");
     mCurrentChunk->Dump(aFile);
     hasChunks = true;
   }
   for (const ProfileBufferChunk* chunk = mNextChunks.get(); chunk;
        chunk = chunk->GetNext()) {
     fprintf(aFile, "N ");
     chunk->Dump(aFile);
     hasChunks = true;
   }
   switch (mRequestedChunkHolder->GetState()) {
     case RequestedChunkRefCountedHolder::State::Unused:
       fprintf(aFile, " - No request pending.\n");
       break;
     case RequestedChunkRefCountedHolder::State::Requested:
       fprintf(aFile, " - Request pending.\n");
       break;
     case RequestedChunkRefCountedHolder::State::Fulfilled:
       fprintf(aFile, " - Request fulfilled.\n");
       break;
   }
   if (!hasChunks) {
     fprintf(aFile, " No chunks.\n");
   }
 }
#endif  // DEBUG

private:
 // Used to de/serialize a ProfileChunkedBuffer (e.g., containing a backtrace).
 friend ProfileBufferEntryWriter::Serializer<ProfileChunkedBuffer>;
 friend ProfileBufferEntryReader::Deserializer<ProfileChunkedBuffer>;
 friend ProfileBufferEntryWriter::Serializer<UniquePtr<ProfileChunkedBuffer>>;
 friend ProfileBufferEntryReader::Deserializer<
     UniquePtr<ProfileChunkedBuffer>>;

 [[nodiscard]] UniquePtr<ProfileBufferChunkManager> ResetChunkManager(
     const baseprofiler::detail::BaseProfilerMaybeAutoLock&) {
   UniquePtr<ProfileBufferChunkManager> chunkManager;
   if (mChunkManager) {
     mRequestedChunkHolder = nullptr;
     mChunkManager->ForgetUnreleasedChunks();
#ifdef DEBUG
     mChunkManager->DeregisteredFrom(this);
#endif
     mChunkManager = nullptr;
     chunkManager = std::move(mOwnedChunkManager);
     if (mCurrentChunk) {
       mCurrentChunk->MarkDone();
       mCurrentChunk = nullptr;
     }
     mNextChunks = nullptr;
     mNextChunkRangeStart = mRangeEnd;
     mRangeStart = mRangeEnd;
     mPushedBlockCount = 0;
     mClearedBlockCount = 0;
     mFailedPutBytes = 0;
   }
   return chunkManager;
 }

 void SetChunkManager(
     ProfileBufferChunkManager& aChunkManager,
     const baseprofiler::detail::BaseProfilerMaybeAutoLock& aLock) {
   MOZ_ASSERT(!mChunkManager);
   mChunkManager = &aChunkManager;
#ifdef DEBUG
   mChunkManager->RegisteredWith(this);
#endif

   mChunkManager->SetChunkDestroyedCallback(
       [this](const ProfileBufferChunk& aChunk) {
         for (;;) {
           ProfileBufferIndex rangeStart = mRangeStart;
           if (MOZ_LIKELY(rangeStart <= aChunk.RangeStart())) {
             if (MOZ_LIKELY(mRangeStart.compareExchange(
                     rangeStart,
                     aChunk.RangeStart() + aChunk.BufferBytes()))) {
               break;
             }
           }
         }
         mClearedBlockCount += aChunk.BlockCount();
       });

   // We start with one chunk right away, and request a following one now
   // so it should be available before the current chunk is full.
   SetAndInitializeCurrentChunk(mChunkManager->GetChunk(), aLock);
   mRequestedChunkHolder = MakeRefPtr<RequestedChunkRefCountedHolder>();
   RequestChunk(aLock);
 }

 [[nodiscard]] size_t SizeOfExcludingThis(
     MallocSizeOf aMallocSizeOf,
     const baseprofiler::detail::BaseProfilerMaybeAutoLock&) const {
   if (MOZ_UNLIKELY(!mChunkManager)) {
     // Out-of-session.
     return 0;
   }
   size_t size = mChunkManager->SizeOfIncludingThis(aMallocSizeOf);
   if (mCurrentChunk) {
     size += mCurrentChunk->SizeOfIncludingThis(aMallocSizeOf);
   }
   if (mNextChunks) {
     size += mNextChunks->SizeOfIncludingThis(aMallocSizeOf);
   }
   return size;
 }

 void InitializeCurrentChunk(
     const baseprofiler::detail::BaseProfilerMaybeAutoLock&) {
   MOZ_ASSERT(!!mCurrentChunk);
   mCurrentChunk->SetRangeStart(mNextChunkRangeStart);
   mNextChunkRangeStart += mCurrentChunk->BufferBytes();
   (void)mCurrentChunk->ReserveInitialBlockAsTail(0);
 }

 void SetAndInitializeCurrentChunk(
     UniquePtr<ProfileBufferChunk>&& aChunk,
     const baseprofiler::detail::BaseProfilerMaybeAutoLock& aLock) {
   mCurrentChunk = std::move(aChunk);
   if (mCurrentChunk) {
     InitializeCurrentChunk(aLock);
   }
 }

 void RequestChunk(
     const baseprofiler::detail::BaseProfilerMaybeAutoLock& aLock) {
   if (HandleRequestedChunk_IsPending(aLock)) {
     // There is already a pending request, don't start a new one.
     return;
   }

   // Ensure the `RequestedChunkHolder` knows we're starting a request.
   mRequestedChunkHolder->StartRequest();

   // Request a chunk, the callback carries a `RefPtr` of the
   // `RequestedChunkHolder`, so it's guaranteed to live until it's invoked,
   // even if this `ProfileChunkedBuffer` changes its `ChunkManager` or is
   // destroyed.
   mChunkManager->RequestChunk(
       [requestedChunkHolder = RefPtr<RequestedChunkRefCountedHolder>(
            mRequestedChunkHolder)](UniquePtr<ProfileBufferChunk> aChunk) {
         requestedChunkHolder->AddRequestedChunk(std::move(aChunk));
       });
 }

 [[nodiscard]] bool HandleRequestedChunk_IsPending(
     const baseprofiler::detail::BaseProfilerMaybeAutoLock& aLock) {
   MOZ_ASSERT(!!mChunkManager);
   MOZ_ASSERT(!!mRequestedChunkHolder);

   if (mRequestedChunkHolder->GetState() ==
       RequestedChunkRefCountedHolder::State::Unused) {
     return false;
   }

   // A request is either in-flight or fulfilled.
   Maybe<UniquePtr<ProfileBufferChunk>> maybeChunk =
       mRequestedChunkHolder->GetChunkIfFulfilled();
   if (maybeChunk.isNothing()) {
     // Request is still pending.
     return true;
   }

   // Since we extracted the provided chunk, the holder should now be unused.
   MOZ_ASSERT(mRequestedChunkHolder->GetState() ==
              RequestedChunkRefCountedHolder::State::Unused);

   // Request has been fulfilled.
   UniquePtr<ProfileBufferChunk>& chunk = *maybeChunk;
   if (chunk) {
     // Try to use as current chunk if needed.
     if (!mCurrentChunk) {
       SetAndInitializeCurrentChunk(std::move(chunk), aLock);
       // We've just received a chunk and made it current, request a next chunk
       // for later.
       MOZ_ASSERT(!mNextChunks);
       RequestChunk(aLock);
       return true;
     }

     if (!mNextChunks) {
       mNextChunks = std::move(chunk);
     } else {
       mNextChunks->InsertNext(std::move(chunk));
     }
   }

   return false;
 }

 // Get a pointer to the next chunk available
 [[nodiscard]] ProfileBufferChunk* GetOrCreateCurrentChunk(
     const baseprofiler::detail::BaseProfilerMaybeAutoLock& aLock) {
   ProfileBufferChunk* current = mCurrentChunk.get();
   if (MOZ_UNLIKELY(!current)) {
     // No current chunk ready.
     MOZ_ASSERT(!mNextChunks,
                "There shouldn't be next chunks when there is no current one");
     // See if a request has recently been fulfilled, ignore pending status.
     (void)HandleRequestedChunk_IsPending(aLock);
     current = mCurrentChunk.get();
     if (MOZ_UNLIKELY(!current)) {
       // There was no pending chunk, try to get one right now.
       // This may still fail, but we can't do anything else about it, the
       // caller must handle the nullptr case.
       // Attempt a request for later.
       SetAndInitializeCurrentChunk(mChunkManager->GetChunk(), aLock);
       current = mCurrentChunk.get();
     }
   }
   return current;
 }

 // Get a pointer to the next chunk available
 [[nodiscard]] ProfileBufferChunk* GetOrCreateNextChunk(
     const baseprofiler::detail::BaseProfilerMaybeAutoLock& aLock) {
   MOZ_ASSERT(!!mCurrentChunk,
              "Why ask for a next chunk when there isn't even a current one?");
   ProfileBufferChunk* next = mNextChunks.get();
   if (MOZ_UNLIKELY(!next)) {
     // No next chunk ready, see if a request has recently been fulfilled,
     // ignore pending status.
     (void)HandleRequestedChunk_IsPending(aLock);
     next = mNextChunks.get();
     if (MOZ_UNLIKELY(!next)) {
       // There was no pending chunk, try to get one right now.
       mNextChunks = mChunkManager->GetChunk();
       next = mNextChunks.get();
       // This may still fail, but we can't do anything else about it, the
       // caller must handle the nullptr case.
       if (MOZ_UNLIKELY(!next)) {
         // Attempt a request for later.
         RequestChunk(aLock);
       }
     }
   }
   return next;
 }

 // Reserve a block of `aCallbackBlockBytes()` size, and invoke and return
 // `aCallback(Maybe<ProfileBufferEntryWriter>&)`. Note that this is the "raw"
 // version that doesn't write the entry size at the beginning of the block.
 // Note: `aCallbackBlockBytes` 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 CallbackBlockBytes, typename Callback>
 auto ReserveAndPutRaw(CallbackBlockBytes&& aCallbackBlockBytes,
                       Callback&& aCallback,
                       baseprofiler::detail::BaseProfilerMaybeAutoLock& aLock,
                       uint64_t aBlockCount = 1) {
   // The entry writer that will point into one or two chunks to write
   // into, empty by default (failure).
   Maybe<ProfileBufferEntryWriter> maybeEntryWriter;

   // The current chunk will be filled if we need to write more than its
   // remaining space.
   bool currentChunkFilled = false;

   // If the current chunk gets filled, we may or may not initialize the next
   // chunk!
   bool nextChunkInitialized = false;

   if (MOZ_LIKELY(mChunkManager)) {
     // In-session.

     const Length blockBytes =
         std::forward<CallbackBlockBytes>(aCallbackBlockBytes)();

     if (ProfileBufferChunk* current = GetOrCreateCurrentChunk(aLock);
         MOZ_LIKELY(current)) {
       if (blockBytes <= current->RemainingBytes()) {
         // Block fits in current chunk with only one span.
         currentChunkFilled = blockBytes == current->RemainingBytes();
         const auto [mem0, blockIndex] = current->ReserveBlock(blockBytes);
         MOZ_ASSERT(mem0.LengthBytes() == blockBytes);
         maybeEntryWriter.emplace(
             mem0, blockIndex,
             ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
                 blockIndex.ConvertToProfileBufferIndex() + blockBytes));
         MOZ_ASSERT(maybeEntryWriter->RemainingBytes() == blockBytes);
         mRangeEnd += blockBytes;
         mPushedBlockCount += aBlockCount;
       } else if (blockBytes >= current->BufferBytes()) {
         // Currently only two buffer chunks are held at a time and it is not
         // possible to write an object that takes up more space than this. In
         // this scenario, silently discard this block of data if it is unable
         // to fit into the two reserved profiler chunks.
         mFailedPutBytes += blockBytes;
       } else {
         // Block doesn't fit fully in current chunk, it needs to overflow into
         // the next one.
         // Whether or not we can write this entry, the current chunk is now
         // considered full, so it will be released. (Otherwise we could refuse
         // this entry, but later accept a smaller entry into this chunk, which
         // would be somewhat inconsistent.)
         currentChunkFilled = true;
         // Make sure the next chunk is available (from a previous request),
         // otherwise create one on the spot.
         if (ProfileBufferChunk* next = GetOrCreateNextChunk(aLock);
             MOZ_LIKELY(next)) {
           // Here, we know we have a current and a next chunk.
           // Reserve head of block at the end of the current chunk.
           const auto [mem0, blockIndex] =
               current->ReserveBlock(current->RemainingBytes());
           MOZ_ASSERT(mem0.LengthBytes() < blockBytes);
           MOZ_ASSERT(current->RemainingBytes() == 0);
           // Set the next chunk range, and reserve the needed space for the
           // tail of the block.
           next->SetRangeStart(mNextChunkRangeStart);
           mNextChunkRangeStart += next->BufferBytes();
           const auto mem1 = next->ReserveInitialBlockAsTail(
               blockBytes - mem0.LengthBytes());
           MOZ_ASSERT(next->RemainingBytes() != 0);
           nextChunkInitialized = true;
           // Block is split in two spans.
           maybeEntryWriter.emplace(
               mem0, mem1, blockIndex,
               ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
                   blockIndex.ConvertToProfileBufferIndex() + blockBytes));
           MOZ_ASSERT(maybeEntryWriter->RemainingBytes() == blockBytes);
           mRangeEnd += blockBytes;
           mPushedBlockCount += aBlockCount;
         } else {
           // Cannot get a new chunk. Record put failure.
           mFailedPutBytes += blockBytes;
         }
       }
     } else {
       // Cannot get a current chunk. Record put failure.
       mFailedPutBytes += blockBytes;
     }
   }  // end of `if (MOZ_LIKELY(mChunkManager))`

   // Here, we either have a `Nothing` (failure), or a non-empty entry writer
   // pointing at the start of the block.

   // After we invoke the callback and return, we may need to handle the
   // current chunk being filled.
   auto handleFilledChunk = MakeScopeExit([&]() {
     // If the entry writer was not already empty, the callback *must* have
     // filled the full entry.
     MOZ_ASSERT(!maybeEntryWriter || maybeEntryWriter->RemainingBytes() == 0);

     if (currentChunkFilled) {
       // Extract current (now filled) chunk.
       UniquePtr<ProfileBufferChunk> filled = std::move(mCurrentChunk);

       if (mNextChunks) {
         // Cycle to the next chunk.
         mCurrentChunk =
             std::exchange(mNextChunks, mNextChunks->ReleaseNext());

         // Make sure it is initialized (it is now the current chunk).
         if (!nextChunkInitialized) {
           InitializeCurrentChunk(aLock);
         }
       }

       // And finally mark filled chunk done and release it.
       filled->MarkDone();
       mChunkManager->ReleaseChunk(std::move(filled));

       // Request another chunk if needed.
       // In most cases, here we should have one current chunk and no next
       // chunk, so we want to do a request so there hopefully will be a next
       // chunk available when the current one gets filled.
       // But we also for a request if we don't even have a current chunk (if
       // it's too late, it's ok because the next `ReserveAndPutRaw` wil just
       // allocate one on the spot.)
       // And if we already have a next chunk, there's no need for more now.
       if (!mCurrentChunk || !mNextChunks) {
         RequestChunk(aLock);
       }
     }
   });

   return std::forward<Callback>(aCallback)(maybeEntryWriter);
 }

 // Reserve a block of `aBlockBytes` size, and invoke and return
 // `aCallback(Maybe<ProfileBufferEntryWriter>&)`. Note that this is the "raw"
 // version that doesn't write the entry size at the beginning of the block.
 template <typename Callback>
 auto ReserveAndPutRaw(Length aBlockBytes, Callback&& aCallback,
                       uint64_t aBlockCount) {
   baseprofiler::detail::BaseProfilerMaybeAutoLock lock(mMutex);
   return ReserveAndPutRaw([aBlockBytes]() { return aBlockBytes; },
                           std::forward<Callback>(aCallback), lock,
                           aBlockCount);
 }

 // Mutex guarding the following members.
 mutable baseprofiler::detail::BaseProfilerMaybeMutex mMutex;

 // Pointer to the current Chunk Manager (or null when out-of-session.)
 // It may be owned locally (see below) or externally.
 ProfileBufferChunkManager* mChunkManager = nullptr;

 // Only non-null when we own the current Chunk Manager.
 UniquePtr<ProfileBufferChunkManager> mOwnedChunkManager;

 UniquePtr<ProfileBufferChunk> mCurrentChunk;

 UniquePtr<ProfileBufferChunk> mNextChunks;

 // Class used to transfer requested chunks from a `ChunkManager` to a
 // `ProfileChunkedBuffer`.
 // It needs to be ref-counted because the request may be fulfilled
 // asynchronously, and either side may be destroyed during the request.
 // It cannot use the `ProfileChunkedBuffer` mutex, because that buffer and its
 // mutex could be destroyed during the request.
 class RequestedChunkRefCountedHolder {
  public:
   enum class State { Unused, Requested, Fulfilled };

   // Get the current state. Note that it may change after the function
   // returns, so it should be used carefully, e.g., `ProfileChunkedBuffer` can
   // see if a request is pending or fulfilled, to avoid starting another
   // request.
   [[nodiscard]] State GetState() const {
     baseprofiler::detail::BaseProfilerAutoLock lock(mRequestMutex);
     return mState;
   }

   // Must be called by `ProfileChunkedBuffer` when it requests a chunk.
   // There cannot be more than one request in-flight.
   void StartRequest() {
     baseprofiler::detail::BaseProfilerAutoLock lock(mRequestMutex);
     MOZ_ASSERT(mState == State::Unused, "Already requested or fulfilled");
     mState = State::Requested;
   }

   // Must be called by the `ChunkManager` with a chunk.
   // If the `ChunkManager` cannot provide a chunk (because of memory limits,
   // or it gets destroyed), it must call this anyway with a nullptr.
   void AddRequestedChunk(UniquePtr<ProfileBufferChunk>&& aChunk) {
     baseprofiler::detail::BaseProfilerAutoLock lock(mRequestMutex);
     MOZ_ASSERT(mState == State::Requested);
     mState = State::Fulfilled;
     mRequestedChunk = std::move(aChunk);
   }

   // The `ProfileChunkedBuffer` can try to extract the provided chunk after a
   // request:
   // - Nothing -> Request is not fulfilled yet.
   // - Some(nullptr) -> The `ChunkManager` was not able to provide a chunk.
   // - Some(chunk) -> Requested chunk.
   [[nodiscard]] Maybe<UniquePtr<ProfileBufferChunk>> GetChunkIfFulfilled() {
     Maybe<UniquePtr<ProfileBufferChunk>> maybeChunk;
     baseprofiler::detail::BaseProfilerAutoLock lock(mRequestMutex);
     MOZ_ASSERT(mState == State::Requested || mState == State::Fulfilled);
     if (mState == State::Fulfilled) {
       mState = State::Unused;
       maybeChunk.emplace(std::move(mRequestedChunk));
     }
     return maybeChunk;
   }

   // Ref-counting implementation. Hand-rolled, because mozilla::RefCounted
   // logs AddRefs and Releases in xpcom, but this object could be AddRef'd
   // by the Base Profiler before xpcom starts, then Release'd by the Gecko
   // Profiler in xpcom, leading to apparent negative leaks.

   void AddRef() {
     baseprofiler::detail::BaseProfilerAutoLock lock(mRequestMutex);
     ++mRefCount;
   }

   void Release() {
     {
       baseprofiler::detail::BaseProfilerAutoLock lock(mRequestMutex);
       if (--mRefCount > 0) {
         return;
       }
     }
     delete this;
   }

  private:
   ~RequestedChunkRefCountedHolder() = default;

   // Mutex guarding the following members.
   mutable baseprofiler::detail::BaseProfilerMutex mRequestMutex;
   int mRefCount = 0;
   State mState = State::Unused;
   UniquePtr<ProfileBufferChunk> mRequestedChunk;
 };

 // Requested-chunk holder, kept alive when in-session, but may also live
 // longer if a request is in-flight.
 RefPtr<RequestedChunkRefCountedHolder> mRequestedChunkHolder;

 // Range start of the next chunk to become current. Starting at 1 because
 // 0 is a reserved index similar to nullptr.
 ProfileBufferIndex mNextChunkRangeStart = 1;

 // Index to the first block.
 // Atomic because it may be increased when a Chunk is destroyed, and the
 // callback may be invoked from anywhere, including from inside one of our
 // locked section, so we cannot protect it with a mutex.
 Atomic<ProfileBufferIndex, MemoryOrdering::ReleaseAcquire> mRangeStart{1};

 // Index past the last block. Equals mRangeStart if empty.
 ProfileBufferIndex mRangeEnd = 1;

 // 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.
 // Atomic because it may be updated when a Chunk is destroyed, and the
 // callback may be invoked from anywhere, including from inside one of our
 // locked section, so we cannot protect it with a mutex.
 Atomic<uint64_t, MemoryOrdering::ReleaseAcquire> mClearedBlockCount{0};

 // Number of bytes that could not be put into this buffer.
 uint64_t mFailedPutBytes = 0;
};

// ----------------------------------------------------------------------------
// ProfileChunkedBuffer serialization

// A ProfileChunkedBuffer can hide another one!
// This will be used to store marker backtraces; They can be read back into a
// UniquePtr<ProfileChunkedBuffer>.
// 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<ProfileChunkedBuffer> {
 static Length Bytes(const ProfileChunkedBuffer& aBuffer) {
   return aBuffer.Read([&](ProfileChunkedBuffer::Reader* aReader) {
     if (!aReader) {
       // Out-of-session, we only need 1 byte to store a length of 0.
       return ULEB128Size<Length>(0);
     }
     ProfileBufferEntryReader reader = aReader->SingleChunkDataAsEntry();
     const ProfileBufferIndex start =
         reader.CurrentBlockIndex().ConvertToProfileBufferIndex();
     const ProfileBufferIndex end =
         reader.NextBlockIndex().ConvertToProfileBufferIndex();
     MOZ_ASSERT(end - start <= std::numeric_limits<Length>::max());
     const Length len = static_cast<Length>(end - start);
     if (len == 0) {
       // In-session but empty, also store a length of 0.
       return ULEB128Size<Length>(0);
     }
     // In-session.
     return static_cast<Length>(ULEB128Size(len) + sizeof(start) + len +
                                sizeof(aBuffer.mPushedBlockCount) +
                                sizeof(aBuffer.mClearedBlockCount));
   });
 }

 static void Write(ProfileBufferEntryWriter& aEW,
                   const ProfileChunkedBuffer& aBuffer) {
   aBuffer.Read([&](ProfileChunkedBuffer::Reader* aReader) {
     if (!aReader) {
       // Out-of-session, only store a length of 0.
       aEW.WriteULEB128<Length>(0);
       return;
     }
     ProfileBufferEntryReader reader = aReader->SingleChunkDataAsEntry();
     const ProfileBufferIndex start =
         reader.CurrentBlockIndex().ConvertToProfileBufferIndex();
     const ProfileBufferIndex end =
         reader.NextBlockIndex().ConvertToProfileBufferIndex();
     MOZ_ASSERT(end - start <= std::numeric_limits<Length>::max());
     const Length len = static_cast<Length>(end - start);
     MOZ_ASSERT(len <= aEW.RemainingBytes());
     if (len == 0) {
       // In-session but empty, only store a length of 0.
       aEW.WriteULEB128<Length>(0);
       return;
     }
     // In-session.
     // Store buffer length, and start index.
     aEW.WriteULEB128(len);
     aEW.WriteObject(start);
     // Write all the bytes.
     aEW.WriteFromReader(reader, reader.RemainingBytes());
     // And write stats.
     aEW.WriteObject(static_cast<uint64_t>(aBuffer.mPushedBlockCount));
     aEW.WriteObject(static_cast<uint64_t>(aBuffer.mClearedBlockCount));
     // Note: Failed pushes are not important to serialize.
   });
 }
};

// A serialized ProfileChunkedBuffer can be read into an empty buffer (either
// out-of-session, or in-session with enough room).
template <>
struct ProfileBufferEntryReader::Deserializer<ProfileChunkedBuffer> {
 static void ReadInto(ProfileBufferEntryReader& aER,
                      ProfileChunkedBuffer& 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<ProfileChunkedBuffer::Length>();
   if (len == 0) {
     // 0-length means an "uninteresting" buffer, just return now.
     return;
   }
   // We have a non-empty buffer to read.

   // Read start and end indices.
   const auto start = aER.ReadObject<ProfileBufferIndex>();
   aBuffer.mRangeStart = start;
   // For now, set the end to be the start (the buffer is still empty). It will
   // be updated in `ReserveAndPutRaw()` below.
   aBuffer.mRangeEnd = start;

   if (aBuffer.IsInSession()) {
     // 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, set a new chunk manager that will
     // provide a single chunk of just the right size.
     aBuffer.SetChunkManager(MakeUnique<ProfileBufferChunkManagerSingle>(len));
     MOZ_ASSERT(aBuffer.BufferLength().value() >= len);
   }

   // Copy bytes into the buffer.
   aBuffer.ReserveAndPutRaw(
       len,
       [&](Maybe<ProfileBufferEntryWriter>& aEW) {
         MOZ_RELEASE_ASSERT(aEW.isSome());
         aEW->WriteFromReader(aER, len);
       },
       0);
   // Finally copy stats.
   aBuffer.mPushedBlockCount = aER.ReadObject<uint64_t>();
   aBuffer.mClearedBlockCount = aER.ReadObject<uint64_t>();
   // Failed puts are not important to keep.
   aBuffer.mFailedPutBytes = 0;
 }

 // We cannot output a ProfileChunkedBuffer object (not copyable), use
 // `ReadInto()` or `aER.ReadObject<UniquePtr<BlocksRinbBuffer>>()` instead.
 static ProfileChunkedBuffer Read(ProfileBufferEntryReader& aER) = delete;
};

// A ProfileChunkedBuffer 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<ProfileChunkedBuffer>> {
 static Length Bytes(const UniquePtr<ProfileChunkedBuffer>& 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 ProfileChunkedBuffer (which could be
   // out-of-session or empty.)
   return SumBytes(*aBufferUPtr);
 }

 static void Write(ProfileBufferEntryWriter& aEW,
                   const UniquePtr<ProfileChunkedBuffer>& 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 ProfileChunkedBuffer (which could be
   // out-of-session or empty.)
   aEW.WriteObject(*aBufferUPtr);
 }
};

// Serialization of a raw pointer to ProfileChunkedBuffer.
// Use Deserializer<UniquePtr<ProfileChunkedBuffer>> to read it back.
template <>
struct ProfileBufferEntryWriter::Serializer<ProfileChunkedBuffer*> {
 static Length Bytes(ProfileChunkedBuffer* 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 ProfileChunkedBuffer (which could be
   // out-of-session or empty.)
   return SumBytes(*aBufferUPtr);
 }

 static void Write(ProfileBufferEntryWriter& aEW,
                   ProfileChunkedBuffer* 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 ProfileChunkedBuffer (which could be
   // out-of-session or empty.)
   aEW.WriteObject(*aBufferUPtr);
 }
};

template <>
struct ProfileBufferEntryReader::Deserializer<UniquePtr<ProfileChunkedBuffer>> {
 static void ReadInto(ProfileBufferEntryReader& aER,
                      UniquePtr<ProfileChunkedBuffer>& aBuffer) {
   aBuffer = Read(aER);
 }

 static UniquePtr<ProfileChunkedBuffer> Read(ProfileBufferEntryReader& aER) {
   UniquePtr<ProfileChunkedBuffer> 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<ProfileChunkedBuffer::Length>();
   if (len == 0) {
     // 0-length means an "uninteresting" buffer, just return nullptr.
     return bufferUPtr;
   }
   // We have a non-empty buffer.
   // allocate an empty ProfileChunkedBuffer without mutex.
   bufferUPtr = MakeUnique<ProfileChunkedBuffer>(
       ProfileChunkedBuffer::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  // ProfileChunkedBuffer_h