mozjemalloc
===========

mozjemalloc is a memory allocator forked from jemalloc, it was forked a
little before jemalloc 2.  The Mozilla team have made many modifications and
this could be considered a parallel evolution of the allocator.


Interface
---------

 * mozjemalloc.h, mozmemory.h, malloc_decls.h, mozmemory_wrap.h and
   mozmemory_wrap.cpp

   The main allocator interface.  mozjemalloc.h defines several classes for
   different implementations and uses malloc_decls.h to substitute in their
   methods.

 * replace_malloc.h and replace_malloc_bridge.h

   The optional replace-malloc interface.  In nightly builds of Firefox we
   can use this to dynamic replace the malloc implementation for testing or
   to support DMD, logalloc or the profiler.

 * mozmemory_stall.h

   Low memory handling.  This interface enables "stalling" when the
   allocator can't get memory from the OS.  By stalling (pausing execution
   for a short time before retrying) it can give the OS a chance to make
   more memory available.

 * mozjemalloc_types.h

   Types such as arena_id_t and jemalloc_stats_t used outside the allocator
   are declared here.


Main components
---------------

 * mozjemalloc.cpp

   The majority of the allocator.

 * BaseAlloc.h and BaseAlloc.cpp

   The base allocator and some template classes to spacialise it.  Some of
   mozjemalloc's bookkeeping structures need dynamic allocation and this is
   what handles it.

 * Chunk.h and Chunk.cpp

   Chunks are 1MiB contigous blocks of memory that the allocator will divide
   into pages and runs.

   These files contain the arena_chunk_t data structure, chunk and page
   allocation functions.  All functions that get and return memory to the OS
   belong here.

 * Constants.h, Globals.h, Globals_inc.h and Globals.cpp

   Compile time constants and other global values.  Globals_inc.h is
   included indirectly depending on whether page size is a compile time
   constant or set at runtime.

   Constants.h doesn't depend on any structure sizes (eg sizeof()) or
   runtime values and may be included in other headers.  Globals.h depends
   on the size of arena_chunk_t and the page size which is sometimes
   determined at runtime.  It depends on Chunk.h.

 * Extent.h

   The extent data structure.

 * Fallback.cpp

   When building without mozjemalloc this file is compiled instead to add
   functions that may be missing on some platforms (memalign) and wrap the
   system allocator in interfaces used by the rest of Firefox (eg arena
   allocation).


Utility code
------------

 * FdPrintf.h and FdPrintf.cpp

   A printf implementation that doesn't need any dynamic allocation.

 * Mutex.h and Mutex.cpp

   The mutex implementation used in the allocator.

 * RedBlackTree.h

   A red-black tree implementation.

 * RadixTree.h

   A radix tree implementation.

 * Utils.h and Utils.cpp

   Other utility code.

 * Zero.h

   Zero and poisoning functions.


PHC
---

 * PHC.h and PHC.cpp

   The probablistic heap checker (PHC) will randomly select a small fraction
   of allocations, it allocates them into a separate area of memory one page
   per allocation and bordered by guard pages.  When free()d, the page is
   'protected' and any use-after-free access will be trapped.  PHC will
   provide the allocation and free stacks to the crash reporter if it
   catches a use-after-free.  PHC also checks for buffer overruns using the
   guard page following the allocation.  Allocations are aligned to the end
   of their page to make overrun detection more likely.


mozalloc
--------

The files in /memory/mozalloc/ provide wrappers for the allocator that make
out-of-memory easier to detect.  An infallible allocator API is also
provided (it aborts rather than returns NULL).


Replace-malloc
--------------

Some builds (eg Firefox Nightly) allow the allocator to be replaced
dynamically to support special features.  These include:

 * /memory/replace/dmd

   The dark matter detector helps developers find allocations not reported
   in Firefox's memory reporters and therefore the `about:memory` page.
   See the README file in that directory.

 * /memory/replace/logalloc

   Logalloc captures every allocator API call (malloc, free, realloc etc)
   and logs it to a file or stdout/stderr.  After some post-processing
   another tool logalloc-replay will "replay" the allocations in the
   allocator for debugging or optimisation.  See the README file in that
   directory.

 * /tools/profiler/core/memory_hooks.{h,cpp}

   The profiler uses the replace-malloc feature to do native allocation
   accounting.  Unlike the other tools it can insert and remove itself after
   the program has started as the profiler requires.