tools/profiler/docs/buffer.rst

   1 Buffers and Memory Management
   2 =============================
   3
   4 In a post-Fission world, precise memory management across many threads and processes is
   5 especially important. In order for the profiler to achieve this, it uses a chunked buffer
   6 strategy.
   7
   8 The `ProfileBuffer`_ is the overall buffer class that controls the memory and storage
   9 for the profile, it allows allocating objects into it. This can be used freely
  10 by things like markers and samples to store data as entries, without needing to know
  11 about the general strategy for how the memory is managed.
  12
  13 The `ProfileBuffer`_ is then backed by the `ProfileChunkedBuffer`_. This specialized
  14 buffer grows incrementally, by allocating additional `ProfileBufferChunk`_ objects.
  15 More and more chunks will be allocated until a memory limit is reached, where they will
  16 be released. After releasing, the chunk will either be recycled or freed.
  17
  18 The limiting of memory usage is coordinated by the `ProfilerParent`_ in the parent
  19 process. The `ProfilerParent`_ and `ProfilerChild`_ exchange IPC messages with information
  20 about how much memory is being used.  When the maximum byte threshold is passed,
  21 the ProfileChunkManager in the parent process removes the oldest chunk, and then the
  22 `ProfilerParent`_ sends a `DestroyReleasedChunksAtOrBefore`_ message to all of child
  23 processes so that the oldest chunks in the profile are released. This helps long profiles
  24 to keep having data in a similar time frame.
  25
  26 Profile Buffer Terminology
  27 ##########################
  28
  29 ProfilerParent
  30   The main profiler machinery is installed in the parent process. It uses IPC to
  31   communicate to the child processes. The PProfiler is the actor which is used
  32   to communicate across processes to coordinate things. See `ProfilerParent.h`_. The
  33   ProfilerParent uses the DestroyReleasedChunksAtOrBefore meessage to control the
  34   overall chunk limit.
  35
  36 ProfilerChild
  37   ProfilerChild is installed in every child process, it will receive requests from
  38   DestroyReleasedChunksAtOrBefore.
  39
  40 Entry
  41   This is an individual entry in the `ProfileBuffer.h`_,. These entry sizes are not
  42   related to the chunks sizes. An individual entry can straddle two different chunks.
  43   An entry can contain various pieces of data, like markers, samples, and stacks.
  44
  45 Chunk
  46   An arbitrary sized chunk of memory, managed by the `ProfileChunkedBuffer`_, and
  47   IPC calls from the ProfilerParent.
  48
  49 Unreleased Chunk
  50   This chunk is currently being used to write entries into.
  51
  52 Released chunk
  53   This chunk is full of data. When memory limits happen, it can either be recycled
  54   or freed.
  55
  56 Recycled chunk
  57   This is a chunk that was previously written into, and full. When memory limits occur,
  58   rather than freeing the memory, it is re-used as the next chunk.
  59
  60 .. _ProfileChunkedBuffer: https://searchfox.org/mozilla-central/search?q=ProfileChunkedBuffer&path=&case=true&regexp=false
  61 .. _ProfileChunkManager: https://searchfox.org/mozilla-central/search?q=ProfileBufferChunkManager.h&path=&case=true&regexp=false
  62 .. _ProfileBufferChunk: https://searchfox.org/mozilla-central/search?q=ProfileBufferChunk&path=&case=true&regexp=false
  63 .. _ProfileBufferChunkManagerWithLocalLimit: https://searchfox.org/mozilla-central/search?q=ProfileBufferChunkManagerWithLocalLimit&case=true&path=
  64 .. _ProfilerParent.h: https://searchfox.org/mozilla-central/source/tools/profiler/public/ProfilerParent.h
  65 .. _ProfilerChild.h: https://searchfox.org/mozilla-central/source/tools/profiler/public/ProfilerChild.h
  66 .. _ProfileBuffer.h: https://searchfox.org/mozilla-central/source/tools/profiler/core/ProfileBuffer.h
  67 .. _ProfileBuffer: https://searchfox.org/mozilla-central/search?q=ProfileBuffer&path=&case=true&regexp=false
  68 .. _ProfilerParent: https://searchfox.org/mozilla-central/search?q=ProfilerParent&path=&case=true&regexp=false
  69 .. _ProfilerChild: https://searchfox.org/mozilla-central/search?q=ProfilerChild&path=&case=true&regexp=false
  70 .. _DestroyReleasedChunksAtOrBefore: https://searchfox.org/mozilla-central/search?q=DestroyReleasedChunksAtOrBefore&path=&case=true&regexp=false