memory/build/malloc_decls.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 // Helper header to declare all the supported malloc functions.
   8 // MALLOC_DECL arguments are:
   9 //   - function name
  10 //   - return type
  11 //   - argument types
  12
  13 #ifndef malloc_decls_h
  14 #  define malloc_decls_h
  15
  16 #  include "mozjemalloc_types.h"
  17
  18 #  define MALLOC_FUNCS_MALLOC_BASE 1
  19 #  define MALLOC_FUNCS_MALLOC_EXTRA 2
  20 #  define MALLOC_FUNCS_MALLOC \
  21     (MALLOC_FUNCS_MALLOC_BASE | MALLOC_FUNCS_MALLOC_EXTRA)
  22 #  define MALLOC_FUNCS_JEMALLOC 4
  23 #  define MALLOC_FUNCS_ARENA_BASE 8
  24 #  define MALLOC_FUNCS_ARENA_ALLOC 16
  25 #  define MALLOC_FUNCS_ARENA \
  26     (MALLOC_FUNCS_ARENA_BASE | MALLOC_FUNCS_ARENA_ALLOC)
  27 #  define MALLOC_FUNCS_ALL \
  28     (MALLOC_FUNCS_MALLOC | MALLOC_FUNCS_JEMALLOC | MALLOC_FUNCS_ARENA)
  29
  30 #endif  // malloc_decls_h
  31
  32 #ifndef MALLOC_FUNCS
  33 #  define MALLOC_FUNCS MALLOC_FUNCS_ALL
  34 #endif
  35
  36 #ifdef MALLOC_DECL
  37 // NOTHROW_MALLOC_DECL is intended for functions where the standard library
  38 // declares the functions in question as `throw()`.  Not all platforms
  39 // consistent declare certain functions as `throw()`, though.
  40
  41 // Bionic and OS X don't seem to care about `throw()`ness.
  42 #  if defined(ANDROID) || defined(XP_DARWIN)
  43 #    undef NOTHROW_MALLOC_DECL
  44 #    define NOTHROW_MALLOC_DECL MALLOC_DECL
  45 // Some places don't care about the distinction.
  46 #  elif !defined(NOTHROW_MALLOC_DECL)
  47 #    define NOTHROW_MALLOC_DECL MALLOC_DECL
  48 #  endif
  49
  50 #  if MALLOC_FUNCS & MALLOC_FUNCS_MALLOC_BASE
  51 MALLOC_DECL(malloc, void*, size_t)
  52 MALLOC_DECL(calloc, void*, size_t, size_t)
  53 MALLOC_DECL(realloc, void*, void*, size_t)
  54 NOTHROW_MALLOC_DECL(free, void, void*)
  55 NOTHROW_MALLOC_DECL(memalign, void*, size_t, size_t)
  56 #  endif
  57 #  if MALLOC_FUNCS & MALLOC_FUNCS_MALLOC_EXTRA
  58 NOTHROW_MALLOC_DECL(posix_memalign, int, void**, size_t, size_t)
  59 NOTHROW_MALLOC_DECL(aligned_alloc, void*, size_t, size_t)
  60 NOTHROW_MALLOC_DECL(valloc, void*, size_t)
  61 NOTHROW_MALLOC_DECL(malloc_usable_size, size_t, usable_ptr_t)
  62 MALLOC_DECL(malloc_good_size, size_t, size_t)
  63 #  endif
  64
  65 #  if MALLOC_FUNCS & MALLOC_FUNCS_JEMALLOC
  66 // The 2nd argument points to an optional array exactly
  67 // jemalloc_stats_num_bins() long to be filled in (if non-null).
  68 // This must only be called on the main thread.
  69 MALLOC_DECL(jemalloc_stats_internal, void, jemalloc_stats_t*,
  70             jemalloc_bin_stats_t*)
  71
  72 // Return the size of the jemalloc_bin_stats_t array.
  73 MALLOC_DECL(jemalloc_stats_num_bins, size_t)
  74
  75 // On some operating systems (Mac), we use madvise(MADV_FREE) to hand pages
  76 // back to the operating system.  On Mac, the operating system doesn't take
  77 // this memory back immediately; instead, the OS takes it back only when the
  78 // machine is running out of physical memory.
  79 //
  80 // This is great from the standpoint of efficiency, but it makes measuring our
  81 // actual RSS difficult, because pages which we've MADV_FREE'd shouldn't count
  82 // against our RSS.
  83 //
  84 // This function explicitly purges any MADV_FREE'd pages from physical memory,
  85 // causing our reported RSS match the amount of memory we're actually using.
  86 //
  87 // Note that this call is expensive in two ways.  First, it may be slow to
  88 // execute, because it may make a number of slow syscalls to free memory.  This
  89 // function holds the big jemalloc locks, so basically all threads are blocked
  90 // while this function runs.
  91 //
  92 // This function is also expensive in that the next time we go to access a page
  93 // which we've just explicitly decommitted, the operating system has to attach
  94 // to it a physical page!  If we hadn't run this function, the OS would have
  95 // less work to do.
  96 //
  97 // If MALLOC_DOUBLE_PURGE is not defined, this function does nothing.
  98 //
  99 // It may only be used from the main thread.
 100 MALLOC_DECL(jemalloc_purge_freed_pages, void)
 101
 102 // Free all unused dirty pages in all arenas. Calling this function will slow
 103 // down subsequent allocations so it is recommended to use it only when
 104 // memory needs to be reclaimed at all costs (see bug 805855). This function
 105 // provides functionality similar to mallctl("arenas.purge") in jemalloc 3.
 106 // It may only be used from the main thread.
 107 MALLOC_DECL(jemalloc_free_dirty_pages, void)
 108
 109 // Opt in or out of a thread local arena (bool argument is whether to opt-in
 110 // (true) or out (false)).
 111 MALLOC_DECL(jemalloc_thread_local_arena, void, bool)
 112
 113 // Provide information about any allocation enclosing the given address.
 114 MALLOC_DECL(jemalloc_ptr_info, void, const void*, jemalloc_ptr_info_t*)
 115
 116 // If jemalloc is currently doing something on this thread then this will return
 117 // true. This is for signal handlers, if jemalloc causes a segfault during free
 118 // (or realloc etc) then this can tell the signal handler that the crashing
 119 // address isn't useful for something like PHC.
 120 MALLOC_DECL(jemalloc_is_working, bool)
 121 #  endif
 122
 123 #  if MALLOC_FUNCS & MALLOC_FUNCS_ARENA_BASE
 124
 125 // Creates a separate arena, and returns its id, valid to use with moz_arena_*
 126 // functions. A helper is provided in mozmemory.h that doesn't take any
 127 // arena_params_t: moz_create_arena.
 128 MALLOC_DECL(moz_create_arena_with_params, arena_id_t, arena_params_t*)
 129
 130 // Dispose of the given arena. Subsequent uses of the arena will crash.
 131 // Passing an invalid id (inexistent or already disposed) to this function
 132 // will crash. The arena must be empty prior to calling this function.
 133 MALLOC_DECL(moz_dispose_arena, void, arena_id_t)
 134
 135 // Set the default modifier for mMaxDirty. The value is the number of shifts
 136 // applied to the value. Positive value is handled as <<, negative >>.
 137 // Arenas may override the default modifier.
 138 MALLOC_DECL(moz_set_max_dirty_page_modifier, void, int32_t)
 139
 140 #  endif
 141
 142 #  if MALLOC_FUNCS & MALLOC_FUNCS_ARENA_ALLOC
 143 // Same as the functions without the moz_arena_ prefix, but using arenas
 144 // created with moz_create_arena.
 145 // The contract, even if not enforced at runtime in some configurations,
 146 // is that moz_arena_realloc and moz_arena_free will crash if the given
 147 // arena doesn't own the given pointer. All functions will crash if the
 148 // arena id is invalid.
 149 // Although discouraged, plain realloc and free can still be used on
 150 // pointers allocated with these functions. Realloc will properly keep
 151 // new pointers in the same arena as the original.
 152 MALLOC_DECL(moz_arena_malloc, void*, arena_id_t, size_t)
 153 MALLOC_DECL(moz_arena_calloc, void*, arena_id_t, size_t, size_t)
 154 MALLOC_DECL(moz_arena_realloc, void*, arena_id_t, void*, size_t)
 155 MALLOC_DECL(moz_arena_free, void, arena_id_t, void*)
 156 MALLOC_DECL(moz_arena_memalign, void*, arena_id_t, size_t, size_t)
 157 #  endif
 158
 159 #endif  // MALLOC_DECL
 160
 161 #undef NOTHROW_MALLOC_DECL
 162 #undef MALLOC_DECL
 163 #undef MALLOC_FUNCS