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*, 102 struct ReplaceMallocBridge**); 103 104 // Replace-malloc library initialization function. See top of this file 105 MOZ_REPLACE_PUBLIC void replace_init( 106 malloc_table_t*, struct ReplaceMallocBridge**) MOZ_REPLACE_WEAK; 107 108 // ensure this is visible and libxul/etc reference it with a weak ref 109 MFBT_API void jemalloc_replace_dynamic(jemalloc_init_func); 110 111 MOZ_END_EXTERN_C 112 113 #endif // replace_malloc_h 114