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 * Mathematical Function Probes::  Probes in mathematical functions
  20 @end menu
  21
  22 @node Memory Allocation Probes
  23 @section Memory Allocation Probes
  24
  25 These probes are designed to signal relatively unusual situations within
  26 the virtual memory subsystem of @theglibc{}.  The location and the
  27 availability of some probes depend on whether per-thread arenas are
  28 enabled (the default) or disabled at the time @theglibc{} is compiled.
  29
  30 @deftp Probe memory_sbrk_more (void *@var{$arg1}, size_t @var{$arg2})
  31 This probe is triggered after the main arena is extended by calling
  32 @code{sbrk}.  Argument @var{$arg1} is the additional size requested to
  33 @code{sbrk}, and @var{$arg2} is the pointer that marks the end of the
  34 @code{sbrk} area, returned in response to the request.
  35 @end deftp
  36
  37 @deftp Probe memory_sbrk_less (void *@var{$arg1}, size_t @var{$arg2})
  38 This probe is triggered after the size of the main arena is decreased by
  39 calling @code{sbrk}.  Argument @var{$arg1} is the size released by
  40 @code{sbrk} (the positive value, rather than the negative value passed
  41 to @code{sbrk}), and @var{$arg2} is the pointer that marks the end of
  42 the @code{sbrk} area, returned in response to the request.
  43 @end deftp
  44
  45 @deftp Probe memory_heap_new (void *@var{$arg1}, size_t @var{$arg2})
  46 This probe is triggered after a new heap is @code{mmap}ed.  Argument
  47 @var{$arg1} is a pointer to the base of the memory area, where the
  48 @code{heap_info} data structure is held, and @var{$arg2} is the size of
  49 the heap.
  50 @end deftp
  51
  52 @deftp Probe memory_heap_free (void *@var{$arg1}, size_t @var{$arg2})
  53 This probe is triggered @emph{before} (unlike the other sbrk and heap
  54 probes) a heap is completely removed via @code{munmap}.  Argument
  55 @var{$arg1} is a pointer to the heap, and @var{$arg2} is the size of the
  56 heap.
  57 @end deftp
  58
  59 @deftp Probe memory_heap_more (void *@var{$arg1}, size_t @var{$arg2})
  60 This probe is triggered after a trailing portion of an @code{mmap}ed
  61 heap is extended.  Argument @var{$arg1} is a pointer to the heap, and
  62 @var{$arg2} is the new size of the heap.
  63 @end deftp
  64
  65 @deftp Probe memory_heap_less (void *@var{$arg1}, size_t @var{$arg2})
  66 This probe is triggered after a trailing portion of an @code{mmap}ed
  67 heap is released.  Argument @var{$arg1} is a pointer to the heap, and
  68 @var{$arg2} is the new size of the heap.
  69 @end deftp
  70
  71 @deftp Probe memory_malloc_retry (size_t @var{$arg1})
  72 @deftpx Probe memory_realloc_retry (size_t @var{$arg1}, void *@var{$arg2})
  73 @deftpx Probe memory_memalign_retry (size_t @var{$arg1}, size_t @var{$arg2})
  74 @deftpx Probe memory_valloc_retry (size_t @var{$arg1})
  75 @deftpx Probe memory_pvalloc_retry (size_t @var{$arg1})
  76 @deftpx Probe memory_calloc_retry (size_t @var{$arg1})
  77 These probes are triggered when the corresponding functions fail to
  78 obtain the requested amount of memory from the arena in use, before they
  79 call @code{arena_get_retry} to select an alternate arena in which to
  80 retry the allocation.  Argument @var{$arg1} is the amount of memory
  81 requested by the user; in the @code{calloc} case, that is the total size
  82 computed from both function arguments.  In the @code{realloc} case,
  83 @var{$arg2} is the pointer to the memory area being resized.  In the
  84 @code{memalign} case, @var{$arg2} is the alignment to be used for the
  85 request, which may be stricter than the value passed to the
  86 @code{memalign} function.
  87
  88 Note that the argument order does @emph{not} match that of the
  89 corresponding two-argument functions, so that in all of these probes the
  90 user-requested allocation size is in @var{$arg1}.
  91 @end deftp
  92
  93 @deftp Probe memory_arena_retry (size_t @var{$arg1}, void *@var{$arg2})
  94 This probe is triggered within @code{arena_get_retry} (the function
  95 called to select the alternate arena in which to retry an allocation
  96 that failed on the first attempt), before the selection of an alternate
  97 arena.  This probe is redundant, but much easier to use when it's not
  98 important to determine which of the various memory allocation functions
  99 is failing to allocate on the first try.  Argument @var{$arg1} is the
 100 same as in the function-specific probes, except for extra room for
 101 padding introduced by functions that have to ensure stricter alignment.
 102 Argument @var{$arg2} is the arena in which allocation failed.
 103 @end deftp
 104
 105 @deftp Probe memory_arena_new (void *@var{$arg1}, size_t @var{$arg2})
 106 This probe is triggered when @code{malloc} allocates and initializes an
 107 additional arena (not the main arena), but before the arena is assigned
 108 to the running thread or inserted into the internal linked list of
 109 arenas.  The arena's @code{malloc_state} internal data structure is
 110 located at @var{$arg1}, within a newly-allocated heap big enough to hold
 111 at least @var{$arg2} bytes.
 112 @end deftp
 113
 114 @deftp Probe memory_arena_reuse (void *@var{$arg1}, void *@var{$arg2})
 115 This probe is triggered when @code{malloc} has just selected an existing
 116 arena to reuse, and (temporarily) reserved it for exclusive use.
 117 Argument @var{$arg1} is a pointer to the newly-selected arena, and
 118 @var{$arg2} is a pointer to the arena previously used by that thread.
 119
 120 When per-thread arenas are enabled, this occurs within
 121 @code{reused_arena}, right after the mutex mentioned in probe
 122 @code{memory_arena_reuse_wait} is acquired; argument @var{$arg1} will
 123 point to the same arena.  In this configuration, this will usually only
 124 occur once per thread.  The exception is when a thread first selected
 125 the main arena, but a subsequent allocation from it fails: then, and
 126 only then, may we switch to another arena to retry that allocations, and
 127 for further allocations within that thread.
 128
 129 When per-thread arenas are disabled, this occurs within
 130 @code{arena_get2}, whenever the mutex for the previously-selected arena
 131 cannot be immediately acquired.
 132 @end deftp
 133
 134 @deftp Probe memory_arena_reuse_wait (void *@var{$arg1}, void *@var{$arg2}, void *@var{$arg3})
 135 This probe is triggered when @code{malloc} is about to wait for an arena
 136 to become available for reuse.  Argument @var{$arg1} holds a pointer to
 137 the mutex the thread is going to wait on, @var{$arg2} is a pointer to a
 138 newly-chosen arena to be reused, and @var{$arg3} is a pointer to the
 139 arena previously used by that thread.
 140
 141 When per-thread arenas are enabled, this occurs within
 142 @code{reused_arena}, when a thread first tries to allocate memory or
 143 needs a retry after a failure to allocate from the main arena, there
 144 isn't any free arena, the maximum number of arenas has been reached, and
 145 an existing arena was chosen for reuse, but its mutex could not be
 146 immediately acquired.  The mutex in @var{$arg1} is the mutex of the
 147 selected arena.
 148
 149 When per-thread arenas are disabled, this occurs within
 150 @code{arena_get2}, when a thread first tries to allocate memory or the
 151 mutex of the arena it previously used could not be immediately acquired,
 152 and none of the existing arenas could be immediately reserved for
 153 exclusive use.  The mutex in @var{$arg1} is that of the list of arenas,
 154 and since the arena won't have been selected yet, @var{$arg2} will be
 155 @code{NULL}.
 156 @end deftp
 157
 158 @deftp Probe memory_arena_reuse_free_list (void *@var{$arg1})
 159 This probe is triggered when @code{malloc} has chosen an arena that is
 160 in the free list for use by a thread, within the @code{get_free_list}
 161 function.  This probe is only available when @code{malloc} is configured
 162 to use per-thread arenas.  The argument @var{$arg1} holds a pointer to
 163 the selected arena.
 164 @end deftp
 165
 166 @deftp Probe memory_arena_reuse_realloc (void *@var{$arg1})
 167 This probe is triggered within @code{realloc}, as the arena of the
 168 current thread is changed to match that in which the given address was
 169 allocated.  This probe is @emph{not} available when @code{malloc} is
 170 configured to use per-thread arenas.  The argument @var{$arg1} holds a
 171 pointer to the newly-selected arena.
 172 @end deftp
 173
 174 @deftp Probe memory_mallopt (int @var{$arg1}, int @var{$arg2})
 175 This probe is triggered when function @code{mallopt} is called to change
 176 @code{malloc} internal configuration parameters, before any change to
 177 the parameters is made.  The arguments @var{$arg1} and @var{$arg2} are
 178 the ones passed to the @code{mallopt} function.
 179 @end deftp
 180
 181 @deftp Probe memory_mallopt_mxfast (int @var{$arg1}, int @var{$arg2})
 182 This probe is triggered shortly after the @code{memory_mallopt} probe,
 183 when the parameter to be changed is @code{M_MXFAST}, and the requested
 184 value is in an acceptable range.  Argument @var{$arg1} is the requested
 185 value, and @var{$arg2} is the previous value of this @code{malloc}
 186 parameter.
 187 @end deftp
 188
 189 @deftp Probe memory_mallopt_trim_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
 190 This probe is triggere shortly after the @code{memory_mallopt} probe,
 191 when the parameter to be changed is @code{M_TRIM_THRESHOLD}.  Argument
 192 @var{$arg1} is the requested value, @var{$arg2} is the previous value of
 193 this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
 194 threshold adjustment was already disabled.
 195 @end deftp
 196
 197 @deftp Probe memory_mallopt_top_pad (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
 198 This probe is triggered shortly after the @code{memory_mallopt} probe,
 199 when the parameter to be changed is @code{M_TOP_PAD}.  Argument
 200 @var{$arg1} is the requested value, @var{$arg2} is the previous value of
 201 this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
 202 threshold adjustment was already disabled.
 203 @end deftp
 204
 205 @deftp Probe memory_mallopt_mmap_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
 206 This probe is triggered shortly after the @code{memory_mallopt} probe,
 207 when the parameter to be changed is @code{M_MMAP_THRESHOLD}, and the
 208 requested value is in an acceptable range.  Argument @var{$arg1} is the
 209 requested value, @var{$arg2} is the previous value of this @code{malloc}
 210 parameter, and @var{$arg3} is nonzero if dynamic threshold adjustment
 211 was already disabled.
 212 @end deftp
 213
 214 @deftp Probe memory_mallopt_mmap_max (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
 215 This probe is triggered shortly after the @code{memory_mallopt} probe,
 216 when the parameter to be changed is @code{M_MMAP_MAX}.  Argument
 217 @var{$arg1} is the requested value, @var{$arg2} is the previous value of
 218 this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
 219 threshold adjustment was already disabled.
 220 @end deftp
 221
 222 @deftp Probe memory_mallopt_check_action (int @var{$arg1}, int @var{$arg2})
 223 This probe is triggered shortly after the @code{memory_mallopt} probe,
 224 when the parameter to be changed is @code{M_CHECK_ACTION}.  Argument
 225 @var{$arg1} is the requested value, and @var{$arg2} is the previous
 226 value of this @code{malloc} parameter.
 227 @end deftp
 228
 229 @deftp Probe memory_mallopt_perturb (int @var{$arg1}, int @var{$arg2})
 230 This probe is triggered shortly after the @code{memory_mallopt} probe,
 231 when the parameter to be changed is @code{M_PERTURB}.  Argument
 232 @var{$arg1} is the requested value, and @var{$arg2} is the previous
 233 value of this @code{malloc} parameter.
 234 @end deftp
 235
 236 @deftp Probe memory_mallopt_arena_test (int @var{$arg1}, int @var{$arg2})
 237 This probe is triggered shortly after the @code{memory_mallopt} probe,
 238 when the parameter to be changed is @code{M_ARENA_TEST}, and the
 239 requested value is in an acceptable range.  Argument @var{$arg1} is the
 240 requested value, and @var{$arg2} is the previous value of this
 241 @code{malloc} parameter.  This probe is only available when per-thread
 242 arenas are enabled.
 243 @end deftp
 244
 245 @deftp Probe memory_mallopt_arena_max (int @var{$arg1}, int @var{$arg2})
 246 This probe is triggered shortly after the @code{memory_mallopt} probe,
 247 when the parameter to be changed is @code{M_ARENA_MAX}, and the
 248 requested value is in an acceptable range.  Argument @var{$arg1} is the
 249 requested value, and @var{$arg2} is the previous value of this
 250 @code{malloc} parameter.  This probe is only available when per-thread
 251 arenas are enabled.
 252 @end deftp
 253
 254 @deftp Probe memory_mallopt_free_dyn_thresholds (int @var{$arg1}, int @var{$arg2})
 255 This probe is triggered when function @code{free} decides to adjust the
 256 dynamic brk/mmap thresholds.  Argument @var{$arg1} and @var{$arg2} are
 257 the adjusted mmap and trim thresholds, respectively.
 258 @end deftp
 259
 260 @node Mathematical Function Probes
 261 @section Mathematical Function Probes
 262
 263 Some mathematical functions fall back to multiple precision arithmetic for
 264 some inputs to get last bit precision for their return values.  This multiple
 265 precision fallback is much slower than the default algorithms and may have a
 266 significant impact on application performance.  The systemtap probe markers
 267 described in this section may help you determine if your application calls
 268 mathematical functions with inputs that may result in multiple-precision
 269 arithmetic.
 270
 271 Unless explicitly mentioned otherwise, a precision of 1 implies 24 bits of
 272 precision in the mantissa of the multiple precision number.  Hence, a precision
 273 level of 32 implies 768 bits of precision in the mantissa.
 274
 275 @deftp Probe slowexp_p6 (double @var{$arg1}, double @var{$arg2})
 276 This probe is hit when the @code{exp} function is called with an input that
 277 results in multiple precision computation with precision 6. Argument
 278 @var{$arg1} is the input value and @var{$arg2} is the computed output.
 279 @end deftp
 280
 281 @deftp Probe slowexp_p32 (double @var{$arg1}, double @var{$arg2})
 282 This probe is hit when the @code{exp} function is called with an input that
 283 results in multiple precision computation with precision 32. Argument
 284 @var{$arg1} is the input value and @var{$arg2} is the computed output.
 285 @end deftp
 286
 287 @deftp Probe slowpow_p10 (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
 288 This probe is hit when the @code{pow} function is called with inputs that
 289 result in multiple precision computation with precision 10. Arguments
 290 @var{$arg1} and @var{$arg2} are the input values, @code{$arg3} is the value
 291 computed in the fast phase of the algorithm and @code{$arg4} is the final
 292 accurate value.
 293 @end deftp
 294
 295 @deftp Probe slowpow_p32 (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
 296 This probe is hit when the @code{pow} function is called with an input that
 297 results in multiple precision computation with precision 32. Arguments
 298 @var{$arg1} and @var{$arg2} are the input values, @code{$arg3} is the value
 299 computed in the fast phase of the algorithm and @code{$arg4} is the final
 300 accurate value.
 301 @end deftp
 302
 303 @deftp Probe slowlog (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
 304 This probe is hit when the @code{log} function is called with an input that
 305 results in multiple precision computation.  Argument @var{$arg1} is the
 306 precision with which the computation succeeded.  Argument @var{$arg2} is the
 307 input and @var{$arg3} is the computed output.
 308 @end deftp
 309
 310 @deftp Probe slowlog_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
 311 This probe is hit when the @code{log} function is called with an input that
 312 results in multiple precision computation and none of the multiple precision
 313 computations result in an accurate result.  Argument @var{$arg1} is the maximum
 314 precision  with which computations were performed.  Argument @var{$arg2} is the
 315 input and @var{$arg3} is the computed output.
 316 @end deftp
 317
 318 @deftp Probe slowatan2 (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
 319 This probe is hit when the @code{atan2} function is called with an input that
 320 results in multiple precision computation.  Argument @var{$arg1} is the
 321 precision with which computation succeeded.  Arguments @var{$arg2} and
 322 @var{$arg3} are inputs to the @code{atan2} function and @var{$arg4} is the
 323 computed result.
 324 @end deftp
 325
 326 @deftp Probe slowatan2_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
 327 This probe is hit when the @code{atan} function is called with an input that
 328 results in multiple precision computation and none of the multiple precision
 329 computations result in an accurate result.  Argument @var{$arg1} is the maximum
 330 precision  with which computations were performed.  Arguments @var{$arg2} and
 331 @var{$arg3} are inputs to the @code{atan2} function and @var{$arg4} is the
 332 computed result.
 333 @end deftp
 334
 335 @deftp Probe slowatan (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
 336 This probe is hit when the @code{atan} function is called with an input that
 337 results in multiple precision computation.  Argument @var{$arg1} is the
 338 precision with which computation succeeded.  Argument @var{$arg2} is the
 339 input to the @code{atan} function and @var{$arg3} is the computed result.
 340 @end deftp
 341
 342 @deftp Probe slowatan_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
 343 This probe is hit when the @code{atan} function is called with an input that
 344 results in multiple precision computation and none of the multiple precision
 345 computations result in an accurate result.  Argument @var{$arg1} is the maximum
 346 precision  with which computations were performed.  Argument @var{$arg2} is the
 347 input to the @code{atan} function and @var{$arg3} is the computed result.
 348 @end deftp
 349
 350 @deftp Probe slowtan (double @var{$arg1}, double @var{$arg2})
 351 This probe is hit when the @code{tan} function is called with an input that
 352 results in multiple precision computation with precision 32.  Argument
 353 @var{$arg1} is the input to the function and @var{$arg2} is the computed
 354 result.
 355 @end deftp