/* -*- 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 ProfileBufferChunk_h
#define ProfileBufferChunk_h
#include "mozilla/MemoryReporting.h"
#include "mozilla/ProfileBufferIndex.h"
#include "mozilla/Span.h"
#include "mozilla/TimeStamp.h"
#include "mozilla/UniquePtr.h"
#if defined(MOZ_MEMORY)
# include
"mozmemory.h"
#endif
#include <algorithm>
#include <limits>
#include <type_traits>
#ifdef DEBUG
# include <cstdio>
#endif
namespace mozilla {
// Represents a single chunk of memory, with a link to the next chunk (or null).
//
// A chunk is made of an internal header (which contains a public part) followed
// by user-accessible bytes.
//
// +---------------+---------+----------------------------------------------+
// | public Header | private | memory containing user blocks |
// +---------------+---------+----------------------------------------------+
// <---------------BufferBytes()------------------>
// <------------------------------ChunkBytes()------------------------------>
//
// The chunk can reserve "blocks", but doesn't know the internal contents of
// each block, it only knows where the first one starts, and where the last one
// ends (which is where the next one will begin, if not already out of range).
// It is up to the user to add structure to each block so that they can be
// distinguished when later read.
//
// +---------------+---------+----------------------------------------------+
// | public Header | private | [1st block]...[last full block] |
// +---------------+---------+----------------------------------------------+
// ChunkHeader().mOffsetFirstBlock ^ ^
// ChunkHeader().mOffsetPastLastBlock --'
//
// It is possible to attempt to reserve more than the remaining space, in which
// case only what is available is returned. The caller is responsible for using
// another chunk, reserving a block "tail" in it, and using both parts to
// constitute a full block. (This initial tail may be empty in some chunks.)
//
// +---------------+---------+----------------------------------------------+
// | public Header | private | tail][1st block]...[last full block][head... |
// +---------------+---------+----------------------------------------------+
// ChunkHeader().mOffsetFirstBlock ^ ^
// ChunkHeader().mOffsetPastLastBlock --'
//
// Each Chunk has an internal state (checked in DEBUG builds) that directs how
// to use it during creation, initialization, use, end of life, recycling, and
// destruction. See `State` below for details.
// In particular:
// - `ReserveInitialBlockAsTail()` must be called before the first `Reserve()`
// after construction or recycling, even with a size of 0 (no actual tail),
// - `MarkDone()` and `MarkRecycled()` must be called as appropriate.
class ProfileBufferChunk {
public:
using Byte = uint8_t;
using Length = uint32_t;
using SpanOfBytes = Span<Byte>;
// Hint about the size of the metadata (public and private headers).
// `Create()` below takes the minimum *buffer* size, so the minimum total
// Chunk size is at least `SizeofChunkMetadata() + aMinBufferBytes`.
[[nodiscard]]
static constexpr Length SizeofChunkMetadata() {
return static_cast<Length>(
sizeof(InternalHeader));
}
// Allocate space for a chunk with a given minimum size, and construct it.
// The actual size may be higher, to match the actual space taken in the
// memory pool.
[[nodiscard]]
static UniquePtr<ProfileBufferChunk> Create(
Length aMinBufferBytes) {
// We need at least one byte, to cover the always-present `mBuffer` byte.
aMinBufferBytes = std::max(aMinBufferBytes, Length(1));
// Trivial struct with the same alignment as `ProfileBufferChunk`, and size
// equal to that alignment, because typically the sizeof of an object is
// a multiple of its alignment.
struct alignas(alignof(InternalHeader)) ChunkStruct {
Byte c[alignof(InternalHeader)];
};
static_assert(std::is_trivial_v<ChunkStruct>,
"ChunkStruct must be trivial to avoid any construction");
// Allocate an array of that struct, enough to contain the expected
// `ProfileBufferChunk` (with its header+buffer).
size_t count = (
sizeof(InternalHeader) + aMinBufferBytes +
(alignof(InternalHeader) - 1)) /
alignof(InternalHeader);
#if defined(MOZ_MEMORY)
// Potentially expand the array to use more of the effective allocation.
count = (malloc_good_size(count *
sizeof(ChunkStruct)) +
(
sizeof(ChunkStruct) - 1)) /
sizeof(ChunkStruct);
#endif
auto chunkStorage = MakeUnique<ChunkStruct[]>(count);
MOZ_ASSERT(
reinterpret_cast<uintptr_t>(chunkStorage.get()) %
alignof(InternalHeader) ==
0);
// After the allocation, compute the actual chunk size (including header).
const size_t chunkBytes = count *
sizeof(ChunkStruct);
MOZ_ASSERT(chunkBytes >=
sizeof(ProfileBufferChunk),
"Not enough space to construct a ProfileBufferChunk");
MOZ_ASSERT(chunkBytes <=
static_cast<size_t>(std::numeric_limits<Length>::max()));
// Compute the size of the user-accessible buffer inside the chunk.
const Length bufferBytes =
static_cast<Length>(chunkBytes -
sizeof(InternalHeader));
MOZ_ASSERT(bufferBytes >= aMinBufferBytes,
"Not enough space for minimum buffer size");
// Construct the header at the beginning of the allocated array, with the
// known buffer size.
new (chunkStorage.get()) ProfileBufferChunk(bufferBytes);
// We now have a proper `ProfileBufferChunk` object, create the appropriate
// UniquePtr for it.
UniquePtr<ProfileBufferChunk> chunk{
reinterpret_cast<ProfileBufferChunk*>(chunkStorage.release())};
MOZ_ASSERT(
size_t(
reinterpret_cast<
const char*>(
&chunk.get()->BufferSpan()[bufferBytes - 1]) -
reinterpret_cast<
const char*>(chunk.get())) == chunkBytes - 1,
"Buffer span spills out of chunk allocation");
return chunk;
}
#ifdef DEBUG
~ProfileBufferChunk() {
MOZ_ASSERT(mInternalHeader.mState != InternalHeader::State::InUse);
MOZ_ASSERT(mInternalHeader.mState != InternalHeader::State::Full);
MOZ_ASSERT(mInternalHeader.mState == InternalHeader::State::Created ||
mInternalHeader.mState == InternalHeader::State::Done ||
mInternalHeader.mState == InternalHeader::State::Recycled);
}
#endif
// Must be called with the first block tail (may be empty), which will be
// skipped if the reader starts with this ProfileBufferChunk.
[[nodiscard]] SpanOfBytes ReserveInitialBlockAsTail(Length aTailSize) {
#ifdef DEBUG
MOZ_ASSERT(mInternalHeader.mState != InternalHeader::State::InUse);
MOZ_ASSERT(mInternalHeader.mState != InternalHeader::State::Full);
MOZ_ASSERT(mInternalHeader.mState != InternalHeader::State::Done);
MOZ_ASSERT(mInternalHeader.mState == InternalHeader::State::Created ||
mInternalHeader.mState == InternalHeader::State::Recycled);
mInternalHeader.mState = InternalHeader::State::InUse;
#endif
mInternalHeader.mHeader.mOffsetFirstBlock = aTailSize;
mInternalHeader.mHeader.mOffsetPastLastBlock = aTailSize;
mInternalHeader.mHeader.mStartTimeStamp = TimeStamp::Now();
return SpanOfBytes(&mBuffer, aTailSize);
}
struct ReserveReturn {
SpanOfBytes mSpan;
ProfileBufferBlockIndex mBlockRangeIndex;
};
// Reserve a block of up to `aBlockSize` bytes, and return a Span to it, and
// its starting index. The actual size may be smaller, if the block cannot fit
// in the remaining space.
[[nodiscard]] ReserveReturn ReserveBlock(Length aBlockSize) {
MOZ_ASSERT(mInternalHeader.mState != InternalHeader::State::Created);
MOZ_ASSERT(mInternalHeader.mState != InternalHeader::State::Full);
MOZ_ASSERT(mInternalHeader.mState != InternalHeader::State::Done);
MOZ_ASSERT(mInternalHeader.mState != InternalHeader::State::Recycled);
MOZ_ASSERT(mInternalHeader.mState == InternalHeader::State::InUse);
MOZ_ASSERT(RangeStart() != 0,
"Expected valid range start before first Reserve()");
const Length blockOffset = mInternalHeader.mHeader.mOffsetPastLastBlock;
Length reservedSize = aBlockSize;
if (MOZ_UNLIKELY(aBlockSize >= RemainingBytes())) {
reservedSize = RemainingBytes();
#ifdef DEBUG
mInternalHeader.mState = InternalHeader::State::Full;
#endif
}
mInternalHeader.mHeader.mOffsetPastLastBlock += reservedSize;
mInternalHeader.mHeader.mBlockCount += 1;
return {SpanOfBytes(&mBuffer + blockOffset, reservedSize),
ProfileBufferBlockIndex::CreateFromProfileBufferIndex(
mInternalHeader.mHeader.mRangeStart + blockOffset)};
}
// When a chunk will not be used to store more blocks (because it is full, or
// because the profiler will not add more data), it should be marked "done".
// Access to its content is still allowed.
void MarkDone() {
#ifdef DEBUG
MOZ_ASSERT(mInternalHeader.mState != InternalHeader::State::Created);
MOZ_ASSERT(mInternalHeader.mState != InternalHeader::State::Done);
MOZ_ASSERT(mInternalHeader.mState != InternalHeader::State::Recycled);
MOZ_ASSERT(mInternalHeader.mState == InternalHeader::State::InUse ||
mInternalHeader.mState == InternalHeader::State::Full);
mInternalHeader.mState = InternalHeader::State::Done;
#endif
mInternalHeader.mHeader.mDoneTimeStamp = TimeStamp::Now();
}
// A "Done" chunk may be recycled, to avoid allocating a new one.
void MarkRecycled() {
#ifdef DEBUG
// We also allow Created and already-Recycled chunks to be recycled, this
// way it's easier to recycle chunks when their state is not easily
// trackable.
MOZ_ASSERT(mInternalHeader.mState != InternalHeader::State::InUse);
MOZ_ASSERT(mInternalHeader.mState != InternalHeader::State::Full);
MOZ_ASSERT(mInternalHeader.mState == InternalHeader::State::Created ||
mInternalHeader.mState == InternalHeader::State::Done ||
mInternalHeader.mState == InternalHeader::State::Recycled);
mInternalHeader.mState = InternalHeader::State::Recycled;
#endif
// Reset all header fields, in case this recycled chunk gets read.
mInternalHeader.mHeader.Reset();
}
// Public header, meant to uniquely identify a chunk, it may be shared with
// other processes to coordinate global memory handling.
struct Header {
explicit Header(Length aBufferBytes) : mBufferBytes(aBufferBytes) {}
// Reset all members to their as-new values (apart from the buffer size,
// which cannot change), ready for re-use.
void Reset() {
mOffsetFirstBlock = 0;
mOffsetPastLastBlock = 0;
mStartTimeStamp = TimeStamp{};
mDoneTimeStamp = TimeStamp{};
mBlockCount = 0;
mRangeStart = 0;
mProcessId = 0;
}
// Note: Part of the ordering of members below is to avoid unnecessary
// padding.
// Members managed by the ProfileBufferChunk.
// Offset of the first block (past the initial tail block, which may be 0).
Length mOffsetFirstBlock = 0;
// Offset past the last byte of the last reserved block
// It may be past mBufferBytes when last block continues in the next
// ProfileBufferChunk. It may be before mBufferBytes if ProfileBufferChunk
// is marked "Done" before the end is reached.
Length mOffsetPastLastBlock = 0;
// Timestamp when the buffer becomes in-use, ready to record data.
TimeStamp mStartTimeStamp;
// Timestamp when the buffer is "Done" (which happens when the last block is
// written). This will be used to find and discard the oldest
// ProfileBufferChunk.
TimeStamp mDoneTimeStamp;
// Number of bytes in the buffer, set once at construction time.
const Length mBufferBytes;
// Number of reserved blocks (including final one even if partial, but
// excluding initial tail).
Length mBlockCount = 0;
// Meta-data set by the user.
// Index of the first byte of this ProfileBufferChunk, relative to all
// Chunks for this process. Index 0 is reserved as nullptr-like index,
// mRangeStart should be set to a non-0 value before the first `Reserve()`.
ProfileBufferIndex mRangeStart = 0;
// Process writing to this ProfileBufferChunk.
int mProcessId = 0;
// A bit of spare space (necessary here because of the alignment due to
// other members), may be later repurposed for extra data.
const int mPADDING = 0;
};
[[nodiscard]]
const Header& ChunkHeader()
const {
return mInternalHeader.mHeader;
}
[[nodiscard]] Length BufferBytes()
const {
return ChunkHeader().mBufferBytes;
}
// Total size of the chunk (buffer + header).
[[nodiscard]] Length ChunkBytes()
const {
return static_cast<Length>(
sizeof(InternalHeader)) + BufferBytes();
}
// Size of external resources, in this case all the following chunks.
[[nodiscard]] size_t SizeOfExcludingThis(MallocSizeOf aMallocSizeOf)
const {
const ProfileBufferChunk*
const next = GetNext();
return next ? next->SizeOfIncludingThis(aMallocSizeOf) : 0;
}
// Size of this chunk and all following ones.
[[nodiscard]] size_t SizeOfIncludingThis(MallocSizeOf aMallocSizeOf)
const {
// Just in case `aMallocSizeOf` falls back on just `sizeof`, make sure we
// account for at least the actual Chunk requested allocation size.
return std::max<size_t>(aMallocSizeOf(
this), ChunkBytes()) +
SizeOfExcludingThis(aMallocSizeOf);
}
[[nodiscard]] Length RemainingBytes()
const {
return BufferBytes() - OffsetPastLastBlock();
}
[[nodiscard]] Length OffsetFirstBlock()
const {
return ChunkHeader().mOffsetFirstBlock;
}
[[nodiscard]] Length OffsetPastLastBlock()
const {
return ChunkHeader().mOffsetPastLastBlock;
}
[[nodiscard]] Length BlockCount()
const {
return ChunkHeader().mBlockCount; }
[[nodiscard]]
int ProcessId()
const {
return ChunkHeader().mProcessId; }
void SetProcessId(
int aProcessId) {
mInternalHeader.mHeader.mProcessId = aProcessId;
}
// Global range index at the start of this Chunk.
[[nodiscard]] ProfileBufferIndex RangeStart()
const {
return ChunkHeader().mRangeStart;
}
void SetRangeStart(ProfileBufferIndex aRangeStart) {
mInternalHeader.mHeader.mRangeStart = aRangeStart;
}
// Get a read-only Span to the buffer. It is up to the caller to decypher the
// contents, based on known offsets and the internal block structure.
[[nodiscard]] Span<
const Byte> BufferSpan()
const {
return Span<
const Byte>(&mBuffer, BufferBytes());
}
[[nodiscard]] Byte ByteAt(Length aOffset)
const {
MOZ_ASSERT(aOffset < OffsetPastLastBlock());
return *(&mBuffer + aOffset);
}
[[nodiscard]] ProfileBufferChunk* GetNext() {
return mInternalHeader.mNext.get();
}
[[nodiscard]]
const ProfileBufferChunk* GetNext()
const {
return mInternalHeader.mNext.get();
}
[[nodiscard]] UniquePtr<ProfileBufferChunk> ReleaseNext() {
return std::move(mInternalHeader.mNext);
}
void InsertNext(UniquePtr<ProfileBufferChunk>&& aChunk) {
if (!aChunk) {
return;
}
aChunk->SetLast(ReleaseNext());
mInternalHeader.mNext = std::move(aChunk);
}
// Find the last chunk in this chain (it may be `this`).
[[nodiscard]] ProfileBufferChunk* Last() {
ProfileBufferChunk* chunk =
this;
for (;;) {
ProfileBufferChunk* next = chunk->GetNext();
if (!next) {
return chunk;
}
chunk = next;
}
}
[[nodiscard]]
const ProfileBufferChunk* Last()
const {
const ProfileBufferChunk* chunk =
this;
for (;;) {
const ProfileBufferChunk* next = chunk->GetNext();
if (!next) {
return chunk;
}
chunk = next;
}
}
void SetLast(UniquePtr<ProfileBufferChunk>&& aChunk) {
if (!aChunk) {
return;
}
Last()->mInternalHeader.mNext = std::move(aChunk);
}
// Join two possibly-null chunk lists.
[[nodiscard]]
static UniquePtr<ProfileBufferChunk> Join(
UniquePtr<ProfileBufferChunk>&& aFirst,
UniquePtr<ProfileBufferChunk>&& aLast) {
if (aFirst) {
aFirst->SetLast(std::move(aLast));
return std::move(aFirst);
}
return std::move(aLast);
}
#ifdef DEBUG
void Dump(std::FILE* aFile = stdout)
const {
fprintf(aFile,
"Chunk[%p] chunkSize=%u bufferSize=%u state=%s rangeStart=%u "
"firstBlockOffset=%u offsetPastLastBlock=%u blockCount=%u",
this,
unsigned(ChunkBytes()),
unsigned(BufferBytes()),
mInternalHeader.StateString(),
unsigned(RangeStart()),
unsigned(OffsetFirstBlock()),
unsigned(OffsetPastLastBlock()),
unsigned(BlockCount()));
const auto len = OffsetPastLastBlock();
constexpr
unsigned columns = 16;
unsigned char ascii[columns + 1];
ascii[columns] =
'\0';
for (Length i = 0; i < len; ++i) {
if (i % columns == 0) {
fprintf(aFile,
"\n %4u=0x%03x:",
unsigned(i),
unsigned(i));
for (
unsigned a = 0; a < columns; ++a) {
ascii[a] =
' ';
}
}
unsigned char sep =
' ';
if (i == OffsetFirstBlock()) {
if (i == OffsetPastLastBlock()) {
sep =
'#';
}
else {
sep =
'[';
}
}
else if (i == OffsetPastLastBlock()) {
sep =
']';
}
unsigned char c = *(&mBuffer + i);
fprintf(aFile,
"%c%02x", sep, c);
if (i == len - 1) {
if (i + 1 == OffsetPastLastBlock()) {
// Special case when last block ends right at the end.
fprintf(aFile,
"]");
}
else {
fprintf(aFile,
" ");
}
}
else if (i % columns == columns - 1) {
fprintf(aFile,
" ");
}
ascii[i % columns] = (c >=
' ' && c <=
'~') ? c :
'.';
if (i % columns == columns - 1) {
fprintf(aFile,
" %s", ascii);
}
}
if (len % columns < columns - 1) {
for (Length i = len % columns; i < columns; ++i) {
fprintf(aFile,
" ");
}
fprintf(aFile,
" %s", ascii);
}
fprintf(aFile,
"\n");
}
#endif // DEBUG
private:
// ProfileBufferChunk constructor. Use static `Create()` to allocate and
// construct a ProfileBufferChunk.
explicit ProfileBufferChunk(Length aBufferBytes)
: mInternalHeader(aBufferBytes) {}
// This internal header starts with the public `Header`, and adds some data
// only necessary for local handling.
// This encapsulation is also necessary to perform placement-new in
// `Create()`.
struct InternalHeader {
explicit InternalHeader(Length aBufferBytes) : mHeader(aBufferBytes) {}
Header mHeader;
UniquePtr<ProfileBufferChunk> mNext;
#ifdef DEBUG
enum class State {
Created,
// Self-set. Just constructed, waiting for initial block tail.
InUse,
// Ready to accept blocks.
Full,
// Self-set. Blocks reach the end (or further).
Done,
// Blocks won't be added anymore.
Recycled
// Still full of data, but expecting an initial block tail.
};
State mState = State::Created;
// Transition table: (X=unexpected)
// Method \ State Created InUse Full Done Recycled
// ReserveInitialBlockAsTail InUse X X X InUse
// Reserve X InUse/Full X X X
// MarkDone X Done Done X X
// MarkRecycled X X X Recycled X
// destructor ok X X ok ok
const char* StateString()
const {
switch (mState) {
case State::Created:
return "Created";
case State::InUse:
return "InUse";
case State::Full:
return "Full";
case State::Done:
return "Done";
case State::Recycled:
return "Recycled";
default:
return "?";
}
}
#else // DEBUG
const char* StateString()
const {
return "(non-DEBUG)"; }
#endif
};
InternalHeader mInternalHeader;
// KEEP THIS LAST!
// First byte of the buffer. Note that ProfileBufferChunk::Create allocates a
// bigger block, such that `mBuffer` is the first of `mBufferBytes` available
// bytes.
// The initialization is not strictly needed, because bytes should only be
// read after they have been written and `mOffsetPastLastBlock` has been
// updated. However:
// - Reviewbot complains that it's not initialized.
// - It's cheap to initialize one byte.
// - In the worst case (reading does happen), zero is not a valid entry size
// and should get caught in entry readers.
Byte mBuffer =
'\0';
};
}
// namespace mozilla
#endif // ProfileBufferChunk_h
