1Notes about the Chrome memory allocator.
2
3Background
4----------
5We use this library as a generic way to fork into any of several allocators.
6Currently we can, at runtime, switch between:
7   the default windows allocator
8   the windows low-fragmentation-heap
9   tcmalloc
10   jemalloc (the heap used most notably within Mozilla Firefox)
11
12The mechanism for hooking LIBCMT in windows is rather tricky.  The core
13problem is that by default, the windows library does not declare malloc and
14free as weak symbols.  Because of this, they cannot be overriden.  To work
15around this, we start with the LIBCMT.LIB, and manually remove all allocator
16related functions from it using the visual studio library tool.  Once removed,
17we can now link against the library and provide custom versions of the 
18allocator related functionality.
19
20
21Source code
22-----------
23This directory contains just the allocator (i.e. shim) layer that switches
24between the different underlying memory allocation implementations.
25
26The tcmalloc and jemalloc libraries originate outside of Chromium
27and exist in ../../third_party/tcmalloc and ../../third_party/jemalloc
28(currently, the actual locations are defined in the allocator.gyp file).
29The third party sources use a vendor-branch SCM pattern to track
30Chromium-specific changes independently from upstream changes.
31
32The general intent is to push local changes upstream so that over
33time we no longer need any forked files.
34
35
36Adding a new allocator
37----------------------
38Adding a new allocator requires definition of the following five functions:
39
40  extern "C" {
41    bool init();
42    void* malloc(size_t s);
43    void* realloc(void* p, size_t s);
44    void free(void* s);
45    size_t msize(void* p);
46  }
47
48All other allocation related functions (new/delete/calloc/etc) have been
49implemented generically to work across all allocators.
50
51
52Usage
53-----
54You can use the different allocators by setting the environment variable
55CHROME_ALLOCATOR to:
56   "tcmalloc"  - TC Malloc (default)
57   "jemalloc"  - JE Malloc
58   "winheap"   - Windows default heap
59   "winlfh"    - Windows Low-Fragmentation heap
60