michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
michael@0:  * You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #ifndef replace_malloc_h
michael@0: #define replace_malloc_h
michael@0: 
michael@0: /*
michael@0:  * The replace_malloc facility allows an external library to replace or
michael@0:  * supplement the jemalloc implementation.
michael@0:  *
michael@0:  * The external library may be hooked by setting one of the following
michael@0:  * environment variables to the library path:
michael@0:  *   - LD_PRELOAD on Linux,
michael@0:  *   - DYLD_INSERT_LIBRARIES on OSX,
michael@0:  *   - MOZ_REPLACE_MALLOC_LIB on Windows and Android.
michael@0:  *
michael@0:  * An initialization function is called before any malloc replacement
michael@0:  * function, and has the following declaration:
michael@0:  *
michael@0:  *   void replace_init(const malloc_table_t *)
michael@0:  *
michael@0:  * The const malloc_table_t pointer given to that function is a table
michael@0:  * containing pointers to the original jemalloc implementation, so that
michael@0:  * replacement functions can call them back if they need to. The pointer
michael@0:  * itself can safely be kept around (no need to copy the table itself).
michael@0:  *
michael@0:  * The functions to be implemented in the external library are of the form:
michael@0:  *
michael@0:  *   void *replace_malloc(size_t size)
michael@0:  *   {
michael@0:  *     // Fiddle with the size if necessary.
michael@0:  *     // orig->malloc doesn't have to be called if the external library
michael@0:  *     // provides its own allocator, but in this case it will have to
michael@0:  *     // implement all functions.
michael@0:  *     void *ptr = orig->malloc(size);
michael@0:  *     // Do whatever you want with the ptr.
michael@0:  *     return ptr;
michael@0:  *   }
michael@0:  *
michael@0:  * where "orig" is the pointer obtained from replace_init.
michael@0:  *
michael@0:  * See malloc_decls.h for a list of functions that can be replaced this
michael@0:  * way. The implementations are all in the form:
michael@0:  *   return_type replace_name(arguments [,...])
michael@0:  *
michael@0:  * They don't all need to be provided.
michael@0:  *
michael@0:  * Building a replace-malloc library is like rocket science. It can end up
michael@0:  * with things blowing up, especially when trying to use complex types, and
michael@0:  * even more especially when these types come from XPCOM or other parts of the
michael@0:  * Mozilla codebase.
michael@0:  * It is recommended to add the following to a replace-malloc implementation's
michael@0:  * Makefile.in:
michael@0:  *   MOZ_GLUE_LDFLAGS = # Don't link against mozglue
michael@0:  *   WRAP_LDFLAGS = # Never wrap malloc function calls with -Wl,--wrap
michael@0:  * and the following to the implementation's moz.build:
michael@0:  *   DISABLE_STL_WRAPPING = True # Avoid STL wrapping
michael@0:  *
michael@0:  * If your replace-malloc implementation lives under memory/replace, these
michael@0:  * are taken care of by memory/replace/defs.mk.
michael@0:  */
michael@0: 
michael@0: /* Implementing a replace-malloc library is incompatible with using mozalloc. */
michael@0: #define MOZ_NO_MOZALLOC 1
michael@0: 
michael@0: #include "mozilla/Types.h"
michael@0: 
michael@0: MOZ_BEGIN_EXTERN_C
michael@0: 
michael@0: #define MALLOC_DECL(name, return_type, ...) \
michael@0:   typedef return_type(name ## _impl_t)(__VA_ARGS__);
michael@0: 
michael@0: #include "malloc_decls.h"
michael@0: 
michael@0: #define MALLOC_DECL(name, return_type, ...) \
michael@0:   name ## _impl_t * name;
michael@0: 
michael@0: typedef struct {
michael@0: #include "malloc_decls.h"
michael@0: } malloc_table_t;
michael@0: 
michael@0: 
michael@0: /* MOZ_NO_REPLACE_FUNC_DECL and MOZ_REPLACE_WEAK are only defined in
michael@0:  * replace_malloc.c. Normally including this header will add function
michael@0:  * definitions. */
michael@0: #ifndef MOZ_NO_REPLACE_FUNC_DECL
michael@0: 
michael@0: #  ifndef MOZ_REPLACE_WEAK
michael@0: #    define MOZ_REPLACE_WEAK
michael@0: #  endif
michael@0: 
michael@0: #  define MALLOC_DECL(name, return_type, ...) \
michael@0:     MOZ_EXPORT return_type replace_ ## name(__VA_ARGS__) MOZ_REPLACE_WEAK;
michael@0: 
michael@0: #  define MALLOC_FUNCS MALLOC_FUNCS_ALL
michael@0: #  include "malloc_decls.h"
michael@0: 
michael@0: #endif /* MOZ_NO_REPLACE_FUNC_DECL */
michael@0: 
michael@0: /*
michael@0:  * posix_memalign, aligned_alloc, memalign and valloc all implement some
michael@0:  * kind of aligned memory allocation. For convenience, replace_posix_memalign,
michael@0:  * replace_aligned_alloc and replace_valloc can be automatically derived from
michael@0:  * memalign when MOZ_REPLACE_ONLY_MEMALIGN is defined before including this
michael@0:  * header. PAGE_SIZE also needs to be defined to the appropriate expression.
michael@0:  */
michael@0: #ifdef MOZ_REPLACE_ONLY_MEMALIGN
michael@0: #include <errno.h>
michael@0: 
michael@0: int replace_posix_memalign(void **ptr, size_t alignment, size_t size)
michael@0: {
michael@0:   if (size == 0) {
michael@0:     *ptr = NULL;
michael@0:     return 0;
michael@0:   }
michael@0:   /* alignment must be a power of two and a multiple of sizeof(void *) */
michael@0:   if (((alignment - 1) & alignment) != 0 || (alignment % sizeof(void *)))
michael@0:     return EINVAL;
michael@0:   *ptr = replace_memalign(alignment, size);
michael@0:   return *ptr ? 0 : ENOMEM;
michael@0: }
michael@0: 
michael@0: void *replace_aligned_alloc(size_t alignment, size_t size)
michael@0: {
michael@0:   /* size should be a multiple of alignment */
michael@0:   if (size % alignment)
michael@0:     return NULL;
michael@0:   return replace_memalign(alignment, size);
michael@0: }
michael@0: 
michael@0: void *replace_valloc(size_t size)
michael@0: {
michael@0:   return replace_memalign(PAGE_SIZE, size);
michael@0: }
michael@0: #endif
michael@0: 
michael@0: MOZ_END_EXTERN_C
michael@0: 
michael@0: #endif /* replace_malloc_h */