tor-browser

ModuloBuffer.h (26575B)

---

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

#include "mozilla/leb128iterator.h"
#include "mozilla/Maybe.h"
#include "mozilla/MemoryReporting.h"
#include "mozilla/NotNull.h"
#include "mozilla/PowerOfTwo.h"
#include "mozilla/ProfileBufferEntrySerialization.h"
#include "mozilla/UniquePtr.h"

#include <functional>
#include <iterator>
#include <limits>
#include <type_traits>

namespace mozilla {

// The ModuloBuffer class is a circular buffer that holds raw byte values, with
// data-read/write helpers.
//
// OffsetT: Type of the internal offset into the buffer of bytes, it should be
// large enough to access all bytes of the buffer. It will also be used as
// Length (in bytes) of the buffer and of any subset. Default uint32_t
// IndexT: Type of the external index, it should be large enough that overflows
// should not happen during the lifetime of the ModuloBuffer.
//
// The basic usage is to create an iterator-like object with `ReaderAt(Index)`
// or `WriterAt(Index)`, and use it to read/write data blobs. Iterators
// automatically manage the wrap-around (through "Modulo", which is effectively
// an AND-masking with the PowerOfTwo buffer size.)
//
// There is zero safety: No thread safety, no checks that iterators may be
// overwriting data that's still to be read, etc. It's up to the caller to add
// adequate checks.
// The intended use is as an underlying buffer for a safer container.
template <typename OffsetT = uint32_t, typename IndexT = uint64_t>
class ModuloBuffer {
public:
 using Byte = uint8_t;
 static_assert(sizeof(Byte) == 1, "ModuloBuffer::Byte must be 1 byte");
 using Offset = OffsetT;
 static_assert(!std::numeric_limits<Offset>::is_signed,
               "ModuloBuffer::Offset must be an unsigned integral type");
 using Length = Offset;
 using Index = IndexT;
 static_assert(!std::numeric_limits<Index>::is_signed,
               "ModuloBuffer::Index must be an unsigned integral type");
 static_assert(sizeof(Index) >= sizeof(Offset),
               "ModuloBuffer::Index size must >= Offset");

 // Create a buffer of the given length.
 explicit ModuloBuffer(PowerOfTwo<Length> aLength)
     : mMask(aLength.Mask()),
       mBuffer(WrapNotNull(new Byte[aLength.Value()])),
       mBufferDeleter([](Byte* aBuffer) { delete[] aBuffer; }) {}

 // Take ownership of an existing buffer. Existing contents is ignored.
 // Done by extracting the raw pointer from UniquePtr<Byte[]>, and adding
 // an equivalent `delete[]` in `mBufferDeleter`.
 ModuloBuffer(UniquePtr<Byte[]> aExistingBuffer, PowerOfTwo<Length> aLength)
     : mMask(aLength.Mask()),
       mBuffer(WrapNotNull(aExistingBuffer.release())),
       mBufferDeleter([](Byte* aBuffer) { delete[] aBuffer; }) {}

 // Use an externally-owned buffer. Existing contents is ignored.
 ModuloBuffer(Byte* aExternalBuffer, PowerOfTwo<Length> aLength)
     : mMask(aLength.Mask()), mBuffer(WrapNotNull(aExternalBuffer)) {}

 // Disallow copying, as we may uniquely own the resource.
 ModuloBuffer(const ModuloBuffer& aOther) = delete;
 ModuloBuffer& operator=(const ModuloBuffer& aOther) = delete;

 // Allow move-construction. Stealing ownership if the original had it.
 // This effectively prevents copy construction, and all assignments; needed so
 // that a ModuloBuffer may be initialized from a separate construction.
 // The moved-from ModuloBuffer still points at the resource but doesn't own
 // it, so it won't try to free it; but accesses are not guaranteed, so it
 // should not be used anymore.
 ModuloBuffer(ModuloBuffer&& aOther)
     : mMask(std::move(aOther.mMask)),
       mBuffer(std::move(aOther.mBuffer)),
       mBufferDeleter(std::move(aOther.mBufferDeleter)) {
   // The above move leaves `aOther.mBufferDeleter` in a valid state but with
   // an unspecified value, so it could theoretically still contain the
   // original function, which would be bad because we don't want aOther to
   // delete the resource that `this` now owns.
   if (aOther.mBufferDeleter) {
     // `aOther` still had a non-empty deleter, reset it.
     aOther.mBufferDeleter = nullptr;
   }
 }

 // Disallow assignment, as we have some `const` members.
 ModuloBuffer& operator=(ModuloBuffer&& aOther) = delete;

 // Destructor, deletes the resource if we uniquely own it.
 ~ModuloBuffer() {
   if (mBufferDeleter) {
     mBufferDeleter(mBuffer);
   }
 }

 PowerOfTwo<Length> BufferLength() const {
   return PowerOfTwo<Length>(mMask.MaskValue() + 1);
 }

 // Size of external resources.
 // Note: `mBufferDeleter`'s potential external data (for its captures) is not
 // included, as it's hidden in the `std::function` implementation.
 size_t SizeOfExcludingThis(MallocSizeOf aMallocSizeOf) const {
   if (!mBufferDeleter) {
     // If we don't have a buffer deleter, assume we don't own the data, so
     // it's probably on the stack, or should be reported by its owner.
     return 0;
   }
   return aMallocSizeOf(mBuffer);
 }

 size_t SizeOfIncludingThis(MallocSizeOf aMallocSizeOf) const {
   return aMallocSizeOf(this) + SizeOfExcludingThis(aMallocSizeOf);
 }

 ProfileBufferEntryReader EntryReaderFromTo(
     Index aStart, Index aEnd, ProfileBufferBlockIndex aBlockIndex,
     ProfileBufferBlockIndex aNextBlockIndex) const {
   using EntrySpan = Span<const ProfileBufferEntryReader::Byte>;
   if (aStart == aEnd) {
     return ProfileBufferEntryReader{};
   }
   // Don't allow over-wrapping.
   MOZ_ASSERT(aEnd - aStart <= mMask.MaskValue() + 1);
   // Start offset in 0 .. (buffer size - 1)
   Offset start = static_cast<Offset>(aStart) & mMask;
   // End offset in 1 .. (buffer size)
   Offset end = (static_cast<Offset>(aEnd - 1) & mMask) + 1;
   if (start < end) {
     // Segment doesn't cross buffer threshold, one span is enough.
     return ProfileBufferEntryReader{EntrySpan(&mBuffer[start], end - start),
                                     aBlockIndex, aNextBlockIndex};
   }
   // Segment crosses buffer threshold, we need one span until the end and one
   // span restarting at the beginning of the buffer.
   return ProfileBufferEntryReader{
       EntrySpan(&mBuffer[start], mMask.MaskValue() + 1 - start),
       EntrySpan(&mBuffer[0], end), aBlockIndex, aNextBlockIndex};
 }

 // Return an entry writer for the given range.
 ProfileBufferEntryWriter EntryWriterFromTo(Index aStart, Index aEnd) const {
   using EntrySpan = Span<ProfileBufferEntryReader::Byte>;
   if (aStart == aEnd) {
     return ProfileBufferEntryWriter{};
   }
   MOZ_ASSERT(aEnd - aStart <= mMask.MaskValue() + 1);
   // Start offset in 0 .. (buffer size - 1)
   Offset start = static_cast<Offset>(aStart) & mMask;
   // End offset in 1 .. (buffer size)
   Offset end = (static_cast<Offset>(aEnd - 1) & mMask) + 1;
   if (start < end) {
     // Segment doesn't cross buffer threshold, one span is enough.
     return ProfileBufferEntryWriter{
         EntrySpan(&mBuffer[start], end - start),
         ProfileBufferBlockIndex::CreateFromProfileBufferIndex(aStart),
         ProfileBufferBlockIndex::CreateFromProfileBufferIndex(aEnd)};
   }
   // Segment crosses buffer threshold, we need one span until the end and one
   // span restarting at the beginning of the buffer.
   return ProfileBufferEntryWriter{
       EntrySpan(&mBuffer[start], mMask.MaskValue() + 1 - start),
       EntrySpan(&mBuffer[0], end),
       ProfileBufferBlockIndex::CreateFromProfileBufferIndex(aStart),
       ProfileBufferBlockIndex::CreateFromProfileBufferIndex(aEnd)};
 }

 // Emplace an entry writer into `aMaybeEntryWriter` for the given range.
 void EntryWriterFromTo(Maybe<ProfileBufferEntryWriter>& aMaybeEntryWriter,
                        Index aStart, Index aEnd) const {
   MOZ_ASSERT(aMaybeEntryWriter.isNothing(),
              "Reference entry writer should be Nothing.");
   using EntrySpan = Span<ProfileBufferEntryReader::Byte>;
   if (aStart == aEnd) {
     return;
   }
   MOZ_ASSERT(aEnd - aStart <= mMask.MaskValue() + 1);
   // Start offset in 0 .. (buffer size - 1)
   Offset start = static_cast<Offset>(aStart) & mMask;
   // End offset in 1 .. (buffer size)
   Offset end = (static_cast<Offset>(aEnd - 1) & mMask) + 1;
   if (start < end) {
     // Segment doesn't cross buffer threshold, one span is enough.
     aMaybeEntryWriter.emplace(
         EntrySpan(&mBuffer[start], end - start),
         ProfileBufferBlockIndex::CreateFromProfileBufferIndex(aStart),
         ProfileBufferBlockIndex::CreateFromProfileBufferIndex(aEnd));
   } else {
     // Segment crosses buffer threshold, we need one span until the end and
     // one span restarting at the beginning of the buffer.
     aMaybeEntryWriter.emplace(
         EntrySpan(&mBuffer[start], mMask.MaskValue() + 1 - start),
         EntrySpan(&mBuffer[0], end),
         ProfileBufferBlockIndex::CreateFromProfileBufferIndex(aStart),
         ProfileBufferBlockIndex::CreateFromProfileBufferIndex(aEnd));
   }
 }

 // All ModuloBuffer operations should be done through this iterator, which has
 // an effectively infinite range. The underlying wrapping-around is hidden.
 // Use `ReaderAt(Index)` or `WriterAt(Index)` to create it.
 //
 // `const Iterator<...>` means the iterator itself cannot change, i.e., it
 // cannot move, and only its const methods are available. Note that these
 // const methods may still be used to modify the buffer contents (e.g.:
 // `operator*()`, `Poke()`).
 //
 // `Iterator</*IsBufferConst=*/true>` means the buffer contents cannot be
 // modified, i.e., write operations are forbidden, but the iterator may still
 // move if non-const itself.
 template <bool IsBufferConst>
 class Iterator {
   // Alias to const- or mutable-`ModuloBuffer` depending on `IsBufferConst`.
   using ConstOrMutableBuffer =
       std::conditional_t<IsBufferConst, const ModuloBuffer, ModuloBuffer>;

   // Implementation note about the strange enable-if's below:
   //   `template <bool NotIBC = !IsBufferConst> enable_if_t<NotIBC>`
   // which intuitively could be simplified to:
   //   `enable_if_t<!IsBufferConst>`
   // The former extra-templated syntax is in fact necessary to delay
   // instantiation of these functions until they are actually needed.
   //
   // If we were just doing `enable_if_t<!IsBufferConst>`, this would only
   // depend on the *class* (`ModuloBuffer<...>::Iterator`), which gets
   // instantiated when a `ModuloBuffer` is created with some template
   // arguments; at that point, all non-templated methods get instantiated, so
   // there's no "SFINAE" happening, and `enable_if_t<...>` is actually doing
   // `typename enable_if<...>::type` on the spot, but there is no `type` if
   // `IsBufferConst` is true, so it just fails right away. E.g.:
   // error: no type named 'type' in 'std::enable_if<false, void>';
   //        'enable_if' cannot be used to disable this declaration
   // note: in instantiation of template type alias 'enable_if_t'
   // > std::enable_if_t<!IsBufferConst> WriteObject(const T& aObject) {
   //       in instantiation of template class
   //       'mozilla::ModuloBuffer<...>::Iterator<true>'
   // > auto it = mb.ReaderAt(1);
   //
   // By adding another template level `template <bool NotIsBufferConst =
   // !IsBufferConst>`, the instantiation is delayed until the function is
   // actually invoked somewhere, e.g. `it.Poke(...);`.
   // So at that invocation point, the compiler looks for a "Poke" name in it,
   // and considers potential template instantiations that could work. The
   // `enable_if_t` is *now* attempted, with `NotIsBufferConst` taking its
   // value from `!IsBufferConst`:
   // - If `IsBufferConst` is false, `NotIsBufferConst` is true,
   // `enable_if<NotIsBufferConst>` does define a `type` (`void` by default),
   // so `enable_if_t` happily becomes `void`, the function exists and may be
   // called.
   // - Otherwise if `IsBufferConst` is true, `NotIsBufferConst` is false,
   // `enable_if<NotIsBufferConst>` does *not* define a `type`, therefore
   // `enable_if_t` produces an error because there is no `type`. Now "SFINAE"
   // happens: This "Substitution Failure Is Not An Error" (by itself)... But
   // then, there are no other functions named "Poke" as requested in the
   // `it.Poke(...);` call, so we are now getting an error (can't find
   // function), as expected because `it` had `IsBufferConst`==true. (But at
   // least the compiler waited until this invocation attempt before outputting
   // an error.)
   //
   // C++ is fun!

  public:
   // These definitions are expected by std functions, to recognize this as an
   // iterator. See https://en.cppreference.com/w/cpp/iterator/iterator_traits
   using difference_type = Index;
   using value_type = Byte;
   using pointer = std::conditional_t<IsBufferConst, const Byte*, Byte*>;
   using reference = std::conditional_t<IsBufferConst, const Byte&, Byte&>;
   using iterator_category = std::random_access_iterator_tag;

   // Can always copy/assign from the same kind of iterator.
   Iterator(const Iterator& aRhs) = default;
   Iterator& operator=(const Iterator& aRhs) = default;

   // Can implicitly copy an Iterator-to-mutable (reader+writer) to
   // Iterator-to-const (reader-only), but not the reverse.
   template <bool IsRhsBufferConst,
             typename = std::enable_if_t<(!IsRhsBufferConst) && IsBufferConst>>
   MOZ_IMPLICIT Iterator(const Iterator<IsRhsBufferConst>& aRhs)
       : mModuloBuffer(aRhs.mModuloBuffer), mIndex(aRhs.mIndex) {}

   // Can implicitly assign from an Iterator-to-mutable (reader+writer) to
   // Iterator-to-const (reader-only), but not the reverse.
   template <bool IsRhsBufferConst,
             typename = std::enable_if_t<(!IsRhsBufferConst) && IsBufferConst>>
   Iterator& operator=(const Iterator<IsRhsBufferConst>& aRhs) {
     mModuloBuffer = aRhs.mModuloBuffer;
     mIndex = aRhs.mIndex;
     return *this;
   }

   // Current location of the iterator in the `Index` range.
   // Note that due to wrapping, multiple indices may effectively point at the
   // same byte in the buffer.
   Index CurrentIndex() const { return mIndex; }

   // Location comparison in the `Index` range. I.e., two `Iterator`s may look
   // unequal, but refer to the same buffer location.
   // Must be on the same buffer.
   bool operator==(const Iterator& aRhs) const {
     MOZ_ASSERT(mModuloBuffer == aRhs.mModuloBuffer);
     return mIndex == aRhs.mIndex;
   }
   bool operator!=(const Iterator& aRhs) const {
     MOZ_ASSERT(mModuloBuffer == aRhs.mModuloBuffer);
     return mIndex != aRhs.mIndex;
   }
   bool operator<(const Iterator& aRhs) const {
     MOZ_ASSERT(mModuloBuffer == aRhs.mModuloBuffer);
     return mIndex < aRhs.mIndex;
   }
   bool operator<=(const Iterator& aRhs) const {
     MOZ_ASSERT(mModuloBuffer == aRhs.mModuloBuffer);
     return mIndex <= aRhs.mIndex;
   }
   bool operator>(const Iterator& aRhs) const {
     MOZ_ASSERT(mModuloBuffer == aRhs.mModuloBuffer);
     return mIndex > aRhs.mIndex;
   }
   bool operator>=(const Iterator& aRhs) const {
     MOZ_ASSERT(mModuloBuffer == aRhs.mModuloBuffer);
     return mIndex >= aRhs.mIndex;
   }

   // Movement in the `Index` range.
   Iterator& operator++() {
     ++mIndex;
     return *this;
   }
   Iterator operator++(int) {
     Iterator here(*mModuloBuffer, mIndex);
     ++mIndex;
     return here;
   }
   Iterator& operator--() {
     --mIndex;
     return *this;
   }
   Iterator operator--(int) {
     Iterator here(*mModuloBuffer, mIndex);
     --mIndex;
     return here;
   }
   Iterator& operator+=(Length aLength) {
     mIndex += aLength;
     return *this;
   }
   Iterator operator+(Length aLength) const {
     return Iterator(*mModuloBuffer, mIndex + aLength);
   }
   friend Iterator operator+(Length aLength, const Iterator& aIt) {
     return aIt + aLength;
   }
   Iterator& operator-=(Length aLength) {
     mIndex -= aLength;
     return *this;
   }
   Iterator operator-(Length aLength) const {
     return Iterator(*mModuloBuffer, mIndex - aLength);
   }

   // Distance from `aRef` to here in the `Index` range.
   // May be negative (as 2's complement) if `aRef > *this`.
   Index operator-(const Iterator& aRef) const {
     MOZ_ASSERT(mModuloBuffer == aRef.mModuloBuffer);
     return mIndex - aRef.mIndex;
   }

   // Dereference a single byte (read-only if `IsBufferConst` is true).
   reference operator*() const {
     return mModuloBuffer->mBuffer[OffsetInBuffer()];
   }

   // Random-access dereference.
   reference operator[](Length aLength) const { return *(*this + aLength); }

   // Write data (if `IsBufferConst` is false) but don't move iterator.
   template <bool NotIsBufferConst = !IsBufferConst>
   std::enable_if_t<NotIsBufferConst> Poke(const void* aSrc,
                                           Length aLength) const {
     // Don't allow data larger than the buffer.
     MOZ_ASSERT(aLength <= mModuloBuffer->BufferLength().Value());
     // Offset inside the buffer (corresponding to our Index).
     Offset offset = OffsetInBuffer();
     // Compute remaining bytes between this offset and the end of the buffer.
     Length remaining = mModuloBuffer->BufferLength().Value() - offset;
     if (MOZ_LIKELY(remaining >= aLength)) {
       // Enough space to write everything before the end.
       memcpy(&mModuloBuffer->mBuffer[offset], aSrc, aLength);
     } else {
       // Not enough space. Write as much as possible before the end.
       memcpy(&mModuloBuffer->mBuffer[offset], aSrc, remaining);
       // And then continue from the beginning of the buffer.
       memcpy(&mModuloBuffer->mBuffer[0],
              static_cast<const Byte*>(aSrc) + remaining,
              (aLength - remaining));
     }
   }

   // Write object data (if `IsBufferConst` is false) but don't move iterator.
   // Note that this copies bytes from the object, with the intent to read them
   // back later. Restricted to trivially-copyable types, which support this
   // without Undefined Behavior!
   template <typename T, bool NotIsBufferConst = !IsBufferConst>
   std::enable_if_t<NotIsBufferConst> PokeObject(const T& aObject) const {
     static_assert(std::is_trivially_copyable<T>::value,
                   "PokeObject<T> - T must be trivially copyable");
     return Poke(&aObject, sizeof(T));
   }

   // Write data (if `IsBufferConst` is false) and move iterator ahead.
   template <bool NotIsBufferConst = !IsBufferConst>
   std::enable_if_t<NotIsBufferConst> Write(const void* aSrc, Length aLength) {
     Poke(aSrc, aLength);
     mIndex += aLength;
   }

   // Write object data (if `IsBufferConst` is false) and move iterator ahead.
   // Note that this copies bytes from the object, with the intent to read them
   // back later. Restricted to trivially-copyable types, which support this
   // without Undefined Behavior!
   template <typename T, bool NotIsBufferConst = !IsBufferConst>
   std::enable_if_t<NotIsBufferConst> WriteObject(const T& aObject) {
     static_assert(std::is_trivially_copyable<T>::value,
                   "WriteObject<T> - T must be trivially copyable");
     return Write(&aObject, sizeof(T));
   }

   // Number of bytes needed to represent `aValue` in unsigned LEB128.
   template <typename T>
   static unsigned ULEB128Size(T aValue) {
     return ::mozilla::ULEB128Size(aValue);
   }

   // Write number as unsigned LEB128 (if `IsBufferConst` is false) and move
   // iterator ahead.
   template <typename T, bool NotIsBufferConst = !IsBufferConst>
   std::enable_if_t<NotIsBufferConst> WriteULEB128(T aValue) {
     ::mozilla::WriteULEB128(aValue, *this);
   }

   // Read data but don't move iterator.
   void Peek(void* aDst, Length aLength) const {
     // Don't allow data larger than the buffer.
     MOZ_ASSERT(aLength <= mModuloBuffer->BufferLength().Value());
     // Offset inside the buffer (corresponding to our Index).
     Offset offset = OffsetInBuffer();
     // Compute remaining bytes between this offset and the end of the buffer.
     Length remaining = mModuloBuffer->BufferLength().Value() - offset;
     if (MOZ_LIKELY(remaining >= aLength)) {
       // Can read everything we need before the end of the buffer.
       memcpy(aDst, &mModuloBuffer->mBuffer[offset], aLength);
     } else {
       // Read as much as possible before the end of the buffer.
       memcpy(aDst, &mModuloBuffer->mBuffer[offset], remaining);
       // And then continue from the beginning of the buffer.
       memcpy(static_cast<Byte*>(aDst) + remaining, &mModuloBuffer->mBuffer[0],
              (aLength - remaining));
     }
   }

   // Read data into an object but don't move iterator.
   // Note that this overwrites `aObject` with bytes from the buffer.
   // Restricted to trivially-copyable types, which support this without
   // Undefined Behavior!
   template <typename T>
   void PeekIntoObject(T& aObject) const {
     static_assert(std::is_trivially_copyable<T>::value,
                   "PeekIntoObject<T> - T must be trivially copyable");
     Peek(&aObject, sizeof(T));
   }

   // Read data as an object but don't move iterator.
   // Note that this creates an default `T` first, and then overwrites it with
   // bytes from the buffer. Restricted to trivially-copyable types, which
   // support this without Undefined Behavior!
   template <typename T>
   T PeekObject() const {
     static_assert(std::is_trivially_copyable<T>::value,
                   "PeekObject<T> - T must be trivially copyable");
     T object;
     PeekIntoObject(object);
     return object;
   }

   // Read data and move iterator ahead.
   void Read(void* aDst, Length aLength) {
     Peek(aDst, aLength);
     mIndex += aLength;
   }

   // Read data into a mutable iterator and move both iterators ahead.
   void ReadInto(Iterator</* IsBufferConst */ false>& aDst, Length aLength) {
     // Don't allow data larger than the buffer.
     MOZ_ASSERT(aLength <= mModuloBuffer->BufferLength().Value());
     MOZ_ASSERT(aLength <= aDst.mModuloBuffer->BufferLength().Value());
     // Offset inside the buffer (corresponding to our Index).
     Offset offset = OffsetInBuffer();
     // Compute remaining bytes between this offset and the end of the buffer.
     Length remaining = mModuloBuffer->BufferLength().Value() - offset;
     if (MOZ_LIKELY(remaining >= aLength)) {
       // Can read everything we need before the end of the buffer.
       aDst.Write(&mModuloBuffer->mBuffer[offset], aLength);
     } else {
       // Read as much as possible before the end of the buffer.
       aDst.Write(&mModuloBuffer->mBuffer[offset], remaining);
       // And then continue from the beginning of the buffer.
       aDst.Write(&mModuloBuffer->mBuffer[0], (aLength - remaining));
     }
     mIndex += aLength;
   }

   // Read data into an object and move iterator ahead.
   // Note that this overwrites `aObject` with bytes from the buffer.
   // Restricted to trivially-copyable types, which support this without
   // Undefined Behavior!
   template <typename T>
   void ReadIntoObject(T& aObject) {
     static_assert(std::is_trivially_copyable<T>::value,
                   "ReadIntoObject<T> - T must be trivially copyable");
     Read(&aObject, sizeof(T));
   }

   // Read data as an object and move iterator ahead.
   // Note that this creates an default `T` first, and then overwrites it with
   // bytes from the buffer. Restricted to trivially-copyable types, which
   // support this without Undefined Behavior!
   template <typename T>
   T ReadObject() {
     static_assert(std::is_trivially_copyable<T>::value,
                   "ReadObject<T> - T must be trivially copyable");
     T object;
     ReadIntoObject(object);
     return object;
   }

   // Read an unsigned LEB128 number and move iterator ahead.
   template <typename T>
   T ReadULEB128() {
     return ::mozilla::ReadULEB128<T>(*this);
   }

  private:
   // Only a ModuloBuffer can instantiate its iterator.
   friend class ModuloBuffer;

   Iterator(ConstOrMutableBuffer& aBuffer, Index aIndex)
       : mModuloBuffer(WrapNotNull(&aBuffer)), mIndex(aIndex) {}

   // Convert the Iterator's mIndex into an offset inside the byte buffer.
   Offset OffsetInBuffer() const {
     return static_cast<Offset>(mIndex) & mModuloBuffer->mMask;
   }

   // ModuloBuffer that this Iterator operates on.
   // Using a non-null pointer instead of a reference, to allow re-assignment
   // of an Iterator variable.
   NotNull<ConstOrMutableBuffer*> mModuloBuffer;

   // Position of this iterator in the wider `Index` range. (Will be wrapped
   // around as needed when actually accessing bytes from the buffer.)
   Index mIndex;
 };

 // Shortcut to iterator to const (read-only) data.
 using Reader = Iterator<true>;
 // Shortcut to iterator to non-const (read/write) data.
 using Writer = Iterator<false>;

 // Create an iterator to const data at the given index.
 Reader ReaderAt(Index aIndex) const { return Reader(*this, aIndex); }

 // Create an iterator to non-const data at the given index.
 Writer WriterAt(Index aIndex) { return Writer(*this, aIndex); }

#ifdef DEBUG
 void Dump() const {
   Length len = BufferLength().Value();
   if (len > 128) {
     len = 128;
   }
   for (Length i = 0; i < len; ++i) {
     printf("%02x ", mBuffer[i]);
   }
   printf("\n");
 }
#endif  // DEBUG

private:
 // Mask used to convert an index to an offset in `mBuffer`
 const PowerOfTwoMask<Offset> mMask;

 // Buffer data. `const NotNull<...>` shows that `mBuffer is `const`, and
 // `Byte* const` shows that the pointer cannot be changed to point at
 // something else, but the pointed-at `Byte`s are writable.
 const NotNull<Byte* const> mBuffer;

 // Function used to release the buffer resource (if needed).
 std::function<void(Byte*)> mBufferDeleter;
};

}  // namespace mozilla

#endif  // ModuloBuffer_h