README (4720B)
1 2 mozjemalloc 3 =========== 4 5 mozjemalloc is a memory allocator forked from jemalloc, it was forked a 6 little before jemalloc 2. The Mozilla team have made many modifications and 7 this could be considered a parallel evolution of the allocator. 8 9 10 Interface 11 --------- 12 13 * mozjemalloc.h, mozmemory.h, malloc_decls.h, mozmemory_wrap.h and 14 mozmemory_wrap.cpp 15 16 The main allocator interface. mozjemalloc.h defines several classes for 17 different implementations and uses malloc_decls.h to substitute in their 18 methods. 19 20 * replace_malloc.h and replace_malloc_bridge.h 21 22 The optional replace-malloc interface. In nightly builds of Firefox we 23 can use this to dynamic replace the malloc implementation for testing or 24 to support DMD, logalloc or the profiler. 25 26 * mozmemory_stall.h 27 28 Low memory handling. This interface enables "stalling" when the 29 allocator can't get memory from the OS. By stalling (pausing execution 30 for a short time before retrying) it can give the OS a chance to make 31 more memory available. 32 33 * mozjemalloc_types.h 34 35 Types such as arena_id_t and jemalloc_stats_t used outside the allocator 36 are declared here. 37 38 39 Main components 40 --------------- 41 42 * mozjemalloc.cpp 43 44 The majority of the allocator. 45 46 * BaseAlloc.h and BaseAlloc.cpp 47 48 The base allocator and some template classes to spacialise it. Some of 49 mozjemalloc's bookkeeping structures need dynamic allocation and this is 50 what handles it. 51 52 * Chunk.h and Chunk.cpp 53 54 Chunks are 1MiB contigous blocks of memory that the allocator will divide 55 into pages and runs. 56 57 These files contain the arena_chunk_t data structure, chunk and page 58 allocation functions. All functions that get and return memory to the OS 59 belong here. 60 61 * Constants.h, Globals.h, Globals_inc.h and Globals.cpp 62 63 Compile time constants and other global values. Globals_inc.h is 64 included indirectly depending on whether page size is a compile time 65 constant or set at runtime. 66 67 Constants.h doesn't depend on any structure sizes (eg sizeof()) or 68 runtime values and may be included in other headers. Globals.h depends 69 on the size of arena_chunk_t and the page size which is sometimes 70 determined at runtime. It depends on Chunk.h. 71 72 * Extent.h 73 74 The extent data structure. 75 76 * Fallback.cpp 77 78 When building without mozjemalloc this file is compiled instead to add 79 functions that may be missing on some platforms (memalign) and wrap the 80 system allocator in interfaces used by the rest of Firefox (eg arena 81 allocation). 82 83 84 Utility code 85 ------------ 86 87 * FdPrintf.h and FdPrintf.cpp 88 89 A printf implementation that doesn't need any dynamic allocation. 90 91 * Mutex.h and Mutex.cpp 92 93 The mutex implementation used in the allocator. 94 95 * RedBlackTree.h 96 97 A red-black tree implementation. 98 99 * RadixTree.h 100 101 A radix tree implementation. 102 103 * Utils.h and Utils.cpp 104 105 Other utility code. 106 107 * Zero.h 108 109 Zero and poisoning functions. 110 111 112 PHC 113 --- 114 115 * PHC.h and PHC.cpp 116 117 The probablistic heap checker (PHC) will randomly select a small fraction 118 of allocations, it allocates them into a separate area of memory one page 119 per allocation and bordered by guard pages. When free()d, the page is 120 'protected' and any use-after-free access will be trapped. PHC will 121 provide the allocation and free stacks to the crash reporter if it 122 catches a use-after-free. PHC also checks for buffer overruns using the 123 guard page following the allocation. Allocations are aligned to the end 124 of their page to make overrun detection more likely. 125 126 127 mozalloc 128 -------- 129 130 The files in /memory/mozalloc/ provide wrappers for the allocator that make 131 out-of-memory easier to detect. An infallible allocator API is also 132 provided (it aborts rather than returns NULL). 133 134 135 Replace-malloc 136 -------------- 137 138 Some builds (eg Firefox Nightly) allow the allocator to be replaced 139 dynamically to support special features. These include: 140 141 * /memory/replace/dmd 142 143 The dark matter detector helps developers find allocations not reported 144 in Firefox's memory reporters and therefore the `about:memory` page. 145 See the README file in that directory. 146 147 * /memory/replace/logalloc 148 149 Logalloc captures every allocator API call (malloc, free, realloc etc) 150 and logs it to a file or stdout/stderr. After some post-processing 151 another tool logalloc-replay will "replay" the allocations in the 152 allocator for debugging or optimisation. See the README file in that 153 directory. 154 155 * /tools/profiler/core/memory_hooks.{h,cpp} 156 157 The profiler uses the replace-malloc feature to do native allocation 158 accounting. Unlike the other tools it can insert and remove itself after 159 the program has started as the profiler requires. 160