memory/build/replace_malloc.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef replace_malloc_h
   8 #define replace_malloc_h
   9
  10 // The replace_malloc facility allows an external library to replace or
  11 // supplement the jemalloc implementation.
  12 //
  13 // The external library may be hooked by setting one of the following
  14 // environment variables to the library path:
  15 //   - LD_PRELOAD on Linux,
  16 //   - DYLD_INSERT_LIBRARIES on OSX,
  17 //   - MOZ_REPLACE_MALLOC_LIB on Windows and Android.
  18 //
  19 // An initialization function is called before any malloc replacement
  20 // function, and has the following declaration:
  21 //
  22 //   void replace_init(malloc_table_t*, ReplaceMallocBridge**)
  23 //
  24 // The malloc_table_t pointer given to that function is a table containing
  25 // pointers to the original allocator implementation, so that replacement
  26 // functions can call them back if they need to. The initialization function
  27 // needs to alter that table to replace the function it wants to replace.
  28 // If it needs the original implementation, it thus needs a copy of the
  29 // original table.
  30 //
  31 // The ReplaceMallocBridge* pointer is an outparam that allows the
  32 // replace_init function to return a pointer to its ReplaceMallocBridge
  33 // (see replace_malloc_bridge.h).
  34 //
  35 // The functions to be implemented in the external library are of the form:
  36 //
  37 //   void* replace_malloc(size_t size)
  38 //   {
  39 //     // Fiddle with the size if necessary.
  40 //     // orig->malloc doesn't have to be called if the external library
  41 //     // provides its own allocator, but in this case it will have to
  42 //     // implement all functions.
  43 //     void *ptr = orig->malloc(size);
  44 //     // Do whatever you want with the ptr.
  45 //     return ptr;
  46 //   }
  47 //
  48 // where "orig" is a pointer to a copy of the table replace_init got.
  49 //
  50 // See malloc_decls.h for a list of functions that can be replaced this
  51 // way. The implementations are all in the form:
  52 //   return_type replace_name(arguments [,...])
  53 //
  54 // They don't all need to be provided.
  55 //
  56 // Building a replace-malloc library is like rocket science. It can end up
  57 // with things blowing up, especially when trying to use complex types, and
  58 // even more especially when these types come from XPCOM or other parts of the
  59 // Mozilla codebase.
  60 // It is recommended to add the following to a replace-malloc implementation's
  61 // moz.build:
  62 //   DISABLE_STL_WRAPPING = True # Avoid STL wrapping
  63 //
  64 // If your replace-malloc implementation lives under memory/replace, these
  65 // are taken care of by memory/replace/defs.mk.
  66
  67 #ifdef replace_malloc_bridge_h
  68 #error Do not include replace_malloc_bridge.h before replace_malloc.h. \
  69   In fact, you only need the latter.
  70 #endif
  71
  72 #define REPLACE_MALLOC_IMPL
  73
  74 #include "replace_malloc_bridge.h"
  75
  76 // Implementing a replace-malloc library is incompatible with using mozalloc.
  77 #define MOZ_NO_MOZALLOC 1
  78
  79 #include "mozilla/MacroArgs.h"
  80 #include "mozilla/Types.h"
  81
  82 MOZ_BEGIN_EXTERN_C
  83
  84 // MOZ_REPLACE_WEAK is only defined in mozjemalloc.cpp. Normally including
  85 // this header will add function definitions.
  86 #ifndef MOZ_REPLACE_WEAK
  87 #define MOZ_REPLACE_WEAK
  88 #endif
  89
  90 // When building a replace-malloc library for static linking, we want
  91 // each to have a different name for their "public" functions.
  92 // The build system defines MOZ_REPLACE_MALLOC_PREFIX in that case.
  93 #ifdef MOZ_REPLACE_MALLOC_PREFIX
  94 #define replace_init MOZ_CONCAT(MOZ_REPLACE_MALLOC_PREFIX, _init)
  95 #define MOZ_REPLACE_PUBLIC
  96 #else
  97 #define MOZ_REPLACE_PUBLIC MOZ_EXPORT
  98 #endif
  99
 100 struct ReplaceMallocBridge;
 101 typedef void (*jemalloc_init_func)(malloc_table_t*, struct ReplaceMallocBridge**);
 102
 103 // Replace-malloc library initialization function. See top of this file
 104 MOZ_REPLACE_PUBLIC void
 105 replace_init(malloc_table_t*, struct ReplaceMallocBridge**) MOZ_REPLACE_WEAK;
 106
 107 // ensure this is visible and libxul/etc reference it with a weak ref
 108 MFBT_API void
 109 jemalloc_replace_dynamic(jemalloc_init_func);
 110
 111 MOZ_END_EXTERN_C
 112
 113 #endif // replace_malloc_h