base/allocator/README

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