manual/probes.texi

   1 @node Internal Probes
   2 @c @node Internal Probes, , POSIX Threads, Top
   3 @c %MENU% Probes to monitor libc internal behavior
   4 @chapter Internal probes
   5
   6 In order to aid in debugging and monitoring internal behavior,
   7 @theglibc{} exposes nearly-zero-overhead SystemTap probes marked with
   8 the @code{libc} provider.
   9
  10 These probes are not part of the @glibcadj{} stable ABI, and they are
  11 subject to change or removal across releases.  Our only promise with
  12 regard to them is that, if we find a need to remove or modify the
  13 arguments of a probe, the modified probe will have a different name, so
  14 that program monitors relying on the old probe will not get unexpected
  15 arguments.
  16
  17 @menu
  18 * Memory Allocation Probes::  Probes in the memory allocation subsystem
  19 @end menu
  20
  21 @node Memory Allocation Probes
  22 @section Memory Allocation Probes
  23
  24 These probes are designed to signal relatively unusual situations within
  25 the virtual memory subsystem of @theglibc{}.  The location and the
  26 availability of some probes depend on whether per-thread arenas are
  27 enabled (the default) or disabled at the time @theglibc{} is compiled.
  28
  29 @deftp Probe memory_arena_new (void *@var{$arg1}, size_t @var{$arg2})
  30 This probe is triggered when @code{malloc} allocates and initializes an
  31 additional arena (not the main arena), but before the arena is assigned
  32 to the running thread or inserted into the internal linked list of
  33 arenas.  The arena's @code{malloc_state} internal data structure is
  34 located at @var{$arg1}, within a newly-allocated heap big enough to hold
  35 at least @var{$arg2} bytes.
  36 @end deftp
  37
  38 @deftp Probe memory_arena_reuse (void *@var{$arg1}, void *@var{$arg2})
  39 This probe is triggered when @code{malloc} has just selected an existing
  40 arena to reuse, and (temporarily) reserved it for exclusive use.
  41 Argument @var{$arg1} is a pointer to the newly-selected arena, and
  42 @var{$arg2} is a pointer to the arena previously used by that thread.
  43
  44 When per-thread arenas are enabled, this occurs within
  45 @code{reused_arena}, right after the mutex mentioned in probe
  46 @code{memory_arena_reuse_wait} is acquired; argument @var{$arg1} will
  47 point to the same arena.  In this configuration, this will usually only
  48 occur once per thread.  The exception is when a thread first selected
  49 the main arena, but a subsequent allocation from it fails: then, and
  50 only then, may we switch to another arena to retry that allocations, and
  51 for further allocations within that thread.
  52
  53 When per-thread arenas are disabled, this occurs within
  54 @code{arena_get2}, whenever the mutex for the previously-selected arena
  55 cannot be immediately acquired.
  56 @end deftp
  57
  58 @deftp Probe memory_arena_reuse_wait (void *@var{$arg1}, void *@var{$arg2}, void *@var{$arg3})
  59 This probe is triggered when @code{malloc} is about to wait for an arena
  60 to become available for reuse.  Argument @var{$arg1} holds a pointer to
  61 the mutex the thread is going to wait on, @var{$arg2} is a pointer to a
  62 newly-chosen arena to be reused, and @var{$arg3} is a pointer to the
  63 arena previously used by that thread.
  64
  65 When per-thread arenas are enabled, this occurs within
  66 @code{reused_arena}, when a thread first tries to allocate memory or
  67 needs a retry after a failure to allocate from the main arena, there
  68 isn't any free arena, the maximum number of arenas has been reached, and
  69 an existing arena was chosen for reuse, but its mutex could not be
  70 immediately acquired.  The mutex in @var{$arg1} is the mutex of the
  71 selected arena.
  72
  73 When per-thread arenas are disabled, this occurs within
  74 @code{arena_get2}, when a thread first tries to allocate memory or the
  75 mutex of the arena it previously used could not be immediately acquired,
  76 and none of the existing arenas could be immediately reserved for
  77 exclusive use.  The mutex in @var{$arg1} is that of the list of arenas,
  78 and since the arena won't have been selected yet, @var{$arg2} will be
  79 @code{NULL}.
  80 @end deftp
  81
  82 @deftp Probe memory_arena_reuse_free_list (void *@var{$arg1})
  83 This probe is triggered when @code{malloc} has chosen an arena that is
  84 in the free list for use by a thread, within the @code{get_free_list}
  85 function.  This probe is only available when @code{malloc} is configured
  86 to use per-thread arenas.  The argument @var{$arg1} holds a pointer to
  87 the selected arena.
  88 @end deftp
  89
  90 @deftp Probe memory_arena_reuse_realloc (void *@var{$arg1})
  91 This probe is triggered within @code{realloc}, as the arena of the
  92 current thread is changed to match that in which the given address was
  93 allocated.  This probe is @emph{not} available when @code{malloc} is
  94 configured to use per-thread arenas.  The argument @var{$arg1} holds a
  95 pointer to the newly-selected arena.
  96 @end deftp
  97
  98 @deftp Probe memory_mallopt (int @var{$arg1}, int @var{$arg2})
  99 This probe is triggered when function @code{mallopt} is called to change
 100 @code{malloc} internal configuration parameters, before any change to
 101 the parameters is made.  The arguments @var{$arg1} and @var{$arg2} are
 102 the ones passed to the @code{mallopt} function.
 103 @end deftp
 104
 105 @deftp Probe memory_mallopt_mxfast (int @var{$arg1}, int @var{$arg2})
 106 This probe is triggered shortly after the @code{memory_mallopt} probe,
 107 when the parameter to be changed is @code{M_MXFAST}, and the requested
 108 value is in an acceptable range.  Argument @var{$arg1} is the requested
 109 value, and @var{$arg2} is the previous value of this @code{malloc}
 110 parameter.
 111 @end deftp
 112
 113 @deftp Probe memory_mallopt_trim_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
 114 This probe is triggere shortly after the @code{memory_mallopt} probe,
 115 when the parameter to be changed is @code{M_TRIM_THRESHOLD}.  Argument
 116 @var{$arg1} is the requested value, @var{$arg2} is the previous value of
 117 this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
 118 threshold adjustment was already disabled.
 119 @end deftp
 120
 121 @deftp Probe memory_mallopt_top_pad (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
 122 This probe is triggered shortly after the @code{memory_mallopt} probe,
 123 when the parameter to be changed is @code{M_TOP_PAD}.  Argument
 124 @var{$arg1} is the requested value, @var{$arg2} is the previous value of
 125 this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
 126 threshold adjustment was already disabled.
 127 @end deftp
 128
 129 @deftp Probe memory_mallopt_mmap_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
 130 This probe is triggered shortly after the @code{memory_mallopt} probe,
 131 when the parameter to be changed is @code{M_MMAP_THRESHOLD}, and the
 132 requested value is in an acceptable range.  Argument @var{$arg1} is the
 133 requested value, @var{$arg2} is the previous value of this @code{malloc}
 134 parameter, and @var{$arg3} is nonzero if dynamic threshold adjustment
 135 was already disabled.
 136 @end deftp
 137
 138 @deftp Probe memory_mallopt_mmap_max (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
 139 This probe is triggered shortly after the @code{memory_mallopt} probe,
 140 when the parameter to be changed is @code{M_MMAP_MAX}.  Argument
 141 @var{$arg1} is the requested value, @var{$arg2} is the previous value of
 142 this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
 143 threshold adjustment was already disabled.
 144 @end deftp
 145
 146 @deftp Probe memory_mallopt_check_action (int @var{$arg1}, int @var{$arg2})
 147 This probe is triggered shortly after the @code{memory_mallopt} probe,
 148 when the parameter to be changed is @code{M_CHECK_ACTION}.  Argument
 149 @var{$arg1} is the requested value, and @var{$arg2} is the previous
 150 value of this @code{malloc} parameter.
 151 @end deftp
 152
 153 @deftp Probe memory_mallopt_perturb (int @var{$arg1}, int @var{$arg2})
 154 This probe is triggered shortly after the @code{memory_mallopt} probe,
 155 when the parameter to be changed is @code{M_PERTURB}.  Argument
 156 @var{$arg1} is the requested value, and @var{$arg2} is the previous
 157 value of this @code{malloc} parameter.
 158 @end deftp
 159
 160 @deftp Probe memory_mallopt_arena_test (int @var{$arg1}, int @var{$arg2})
 161 This probe is triggered shortly after the @code{memory_mallopt} probe,
 162 when the parameter to be changed is @code{M_ARENA_TEST}, and the
 163 requested value is in an acceptable range.  Argument @var{$arg1} is the
 164 requested value, and @var{$arg2} is the previous value of this
 165 @code{malloc} parameter.  This probe is only available when per-thread
 166 arenas are enabled.
 167 @end deftp
 168
 169 @deftp Probe memory_mallopt_arena_max (int @var{$arg1}, int @var{$arg2})
 170 This probe is triggered shortly after the @code{memory_mallopt} probe,
 171 when the parameter to be changed is @code{M_ARENA_MAX}, and the
 172 requested value is in an acceptable range.  Argument @var{$arg1} is the
 173 requested value, and @var{$arg2} is the previous value of this
 174 @code{malloc} parameter.  This probe is only available when per-thread
 175 arenas are enabled.
 176 @end deftp
 177
 178 @deftp Probe memory_mallopt_free_dyn_thresholds (int @var{$arg1}, int @var{$arg2})
 179 This probe is triggered when function @code{free} decides to adjust the
 180 dynamic brk/mmap thresholds.  Argument @var{$arg1} and @var{$arg2} are
 181 the adjusted mmap and trim thresholds, respectively.
 182 @end deftp