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_calloc_retry (size_t @var{$arg1})
  75 These probes are triggered when the corresponding functions fail to
  76 obtain the requested amount of memory from the arena in use, before they
  77 call @code{arena_get_retry} to select an alternate arena in which to
  78 retry the allocation.  Argument @var{$arg1} is the amount of memory
  79 requested by the user; in the @code{calloc} case, that is the total size
  80 computed from both function arguments.  In the @code{realloc} case,
  81 @var{$arg2} is the pointer to the memory area being resized.  In the
  82 @code{memalign} case, @var{$arg2} is the alignment to be used for the
  83 request, which may be stricter than the value passed to the
  84 @code{memalign} function.  A @code{memalign} probe is also used by functions
  85 @code{posix_memalign, valloc} and @code{pvalloc}.
  86
  87 Note that the argument order does @emph{not} match that of the
  88 corresponding two-argument functions, so that in all of these probes the
  89 user-requested allocation size is in @var{$arg1}.
  90 @end deftp
  91
  92 @deftp Probe memory_arena_retry (size_t @var{$arg1}, void *@var{$arg2})
  93 This probe is triggered within @code{arena_get_retry} (the function
  94 called to select the alternate arena in which to retry an allocation
  95 that failed on the first attempt), before the selection of an alternate
  96 arena.  This probe is redundant, but much easier to use when it's not
  97 important to determine which of the various memory allocation functions
  98 is failing to allocate on the first try.  Argument @var{$arg1} is the
  99 same as in the function-specific probes, except for extra room for
 100 padding introduced by functions that have to ensure stricter alignment.
 101 Argument @var{$arg2} is the arena in which allocation failed.
 102 @end deftp
 103
 104 @deftp Probe memory_arena_new (void *@var{$arg1}, size_t @var{$arg2})
 105 This probe is triggered when @code{malloc} allocates and initializes an
 106 additional arena (not the main arena), but before the arena is assigned
 107 to the running thread or inserted into the internal linked list of
 108 arenas.  The arena's @code{malloc_state} internal data structure is
 109 located at @var{$arg1}, within a newly-allocated heap big enough to hold
 110 at least @var{$arg2} bytes.
 111 @end deftp
 112
 113 @deftp Probe memory_arena_reuse (void *@var{$arg1}, void *@var{$arg2})
 114 This probe is triggered when @code{malloc} has just selected an existing
 115 arena to reuse, and (temporarily) reserved it for exclusive use.
 116 Argument @var{$arg1} is a pointer to the newly-selected arena, and
 117 @var{$arg2} is a pointer to the arena previously used by that thread.
 118
 119 When per-thread arenas are enabled, this occurs within
 120 @code{reused_arena}, right after the mutex mentioned in probe
 121 @code{memory_arena_reuse_wait} is acquired; argument @var{$arg1} will
 122 point to the same arena.  In this configuration, this will usually only
 123 occur once per thread.  The exception is when a thread first selected
 124 the main arena, but a subsequent allocation from it fails: then, and
 125 only then, may we switch to another arena to retry that allocations, and
 126 for further allocations within that thread.
 127
 128 When per-thread arenas are disabled, this occurs within
 129 @code{arena_get2}, whenever the mutex for the previously-selected arena
 130 cannot be immediately acquired.
 131 @end deftp
 132
 133 @deftp Probe memory_arena_reuse_wait (void *@var{$arg1}, void *@var{$arg2}, void *@var{$arg3})
 134 This probe is triggered when @code{malloc} is about to wait for an arena
 135 to become available for reuse.  Argument @var{$arg1} holds a pointer to
 136 the mutex the thread is going to wait on, @var{$arg2} is a pointer to a
 137 newly-chosen arena to be reused, and @var{$arg3} is a pointer to the
 138 arena previously used by that thread.
 139
 140 When per-thread arenas are enabled, this occurs within
 141 @code{reused_arena}, when a thread first tries to allocate memory or
 142 needs a retry after a failure to allocate from the main arena, there
 143 isn't any free arena, the maximum number of arenas has been reached, and
 144 an existing arena was chosen for reuse, but its mutex could not be
 145 immediately acquired.  The mutex in @var{$arg1} is the mutex of the
 146 selected arena.
 147
 148 When per-thread arenas are disabled, this occurs within
 149 @code{arena_get2}, when a thread first tries to allocate memory or the
 150 mutex of the arena it previously used could not be immediately acquired,
 151 and none of the existing arenas could be immediately reserved for
 152 exclusive use.  The mutex in @var{$arg1} is that of the list of arenas,
 153 and since the arena won't have been selected yet, @var{$arg2} will be
 154 @code{NULL}.
 155 @end deftp
 156
 157 @deftp Probe memory_arena_reuse_free_list (void *@var{$arg1})
 158 This probe is triggered when @code{malloc} has chosen an arena that is
 159 in the free list for use by a thread, within the @code{get_free_list}
 160 function.  This probe is only available when @code{malloc} is configured
 161 to use per-thread arenas.  The argument @var{$arg1} holds a pointer to
 162 the selected arena.
 163 @end deftp
 164
 165 @deftp Probe memory_arena_reuse_realloc (void *@var{$arg1})
 166 This probe is triggered within @code{realloc}, as the arena of the
 167 current thread is changed to match that in which the given address was
 168 allocated.  This probe is @emph{not} available when @code{malloc} is
 169 configured to use per-thread arenas.  The argument @var{$arg1} holds a
 170 pointer to the newly-selected arena.
 171 @end deftp
 172
 173 @deftp Probe memory_mallopt (int @var{$arg1}, int @var{$arg2})
 174 This probe is triggered when function @code{mallopt} is called to change
 175 @code{malloc} internal configuration parameters, before any change to
 176 the parameters is made.  The arguments @var{$arg1} and @var{$arg2} are
 177 the ones passed to the @code{mallopt} function.
 178 @end deftp
 179
 180 @deftp Probe memory_mallopt_mxfast (int @var{$arg1}, int @var{$arg2})
 181 This probe is triggered shortly after the @code{memory_mallopt} probe,
 182 when the parameter to be changed is @code{M_MXFAST}, and the requested
 183 value is in an acceptable range.  Argument @var{$arg1} is the requested
 184 value, and @var{$arg2} is the previous value of this @code{malloc}
 185 parameter.
 186 @end deftp
 187
 188 @deftp Probe memory_mallopt_trim_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
 189 This probe is triggere shortly after the @code{memory_mallopt} probe,
 190 when the parameter to be changed is @code{M_TRIM_THRESHOLD}.  Argument
 191 @var{$arg1} is the requested value, @var{$arg2} is the previous value of
 192 this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
 193 threshold adjustment was already disabled.
 194 @end deftp
 195
 196 @deftp Probe memory_mallopt_top_pad (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
 197 This probe is triggered shortly after the @code{memory_mallopt} probe,
 198 when the parameter to be changed is @code{M_TOP_PAD}.  Argument
 199 @var{$arg1} is the requested value, @var{$arg2} is the previous value of
 200 this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
 201 threshold adjustment was already disabled.
 202 @end deftp
 203
 204 @deftp Probe memory_mallopt_mmap_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
 205 This probe is triggered shortly after the @code{memory_mallopt} probe,
 206 when the parameter to be changed is @code{M_MMAP_THRESHOLD}, and the
 207 requested value is in an acceptable range.  Argument @var{$arg1} is the
 208 requested value, @var{$arg2} is the previous value of this @code{malloc}
 209 parameter, and @var{$arg3} is nonzero if dynamic threshold adjustment
 210 was already disabled.
 211 @end deftp
 212
 213 @deftp Probe memory_mallopt_mmap_max (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
 214 This probe is triggered shortly after the @code{memory_mallopt} probe,
 215 when the parameter to be changed is @code{M_MMAP_MAX}.  Argument
 216 @var{$arg1} is the requested value, @var{$arg2} is the previous value of
 217 this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
 218 threshold adjustment was already disabled.
 219 @end deftp
 220
 221 @deftp Probe memory_mallopt_check_action (int @var{$arg1}, int @var{$arg2})
 222 This probe is triggered shortly after the @code{memory_mallopt} probe,
 223 when the parameter to be changed is @code{M_CHECK_ACTION}.  Argument
 224 @var{$arg1} is the requested value, and @var{$arg2} is the previous
 225 value of this @code{malloc} parameter.
 226 @end deftp
 227
 228 @deftp Probe memory_mallopt_perturb (int @var{$arg1}, int @var{$arg2})
 229 This probe is triggered shortly after the @code{memory_mallopt} probe,
 230 when the parameter to be changed is @code{M_PERTURB}.  Argument
 231 @var{$arg1} is the requested value, and @var{$arg2} is the previous
 232 value of this @code{malloc} parameter.
 233 @end deftp
 234
 235 @deftp Probe memory_mallopt_arena_test (int @var{$arg1}, int @var{$arg2})
 236 This probe is triggered shortly after the @code{memory_mallopt} probe,
 237 when the parameter to be changed is @code{M_ARENA_TEST}, and the
 238 requested value is in an acceptable range.  Argument @var{$arg1} is the
 239 requested value, and @var{$arg2} is the previous value of this
 240 @code{malloc} parameter.  This probe is only available when per-thread
 241 arenas are enabled.
 242 @end deftp
 243
 244 @deftp Probe memory_mallopt_arena_max (int @var{$arg1}, int @var{$arg2})
 245 This probe is triggered shortly after the @code{memory_mallopt} probe,
 246 when the parameter to be changed is @code{M_ARENA_MAX}, and the
 247 requested value is in an acceptable range.  Argument @var{$arg1} is the
 248 requested value, and @var{$arg2} is the previous value of this
 249 @code{malloc} parameter.  This probe is only available when per-thread
 250 arenas are enabled.
 251 @end deftp
 252
 253 @deftp Probe memory_mallopt_free_dyn_thresholds (int @var{$arg1}, int @var{$arg2})
 254 This probe is triggered when function @code{free} decides to adjust the
 255 dynamic brk/mmap thresholds.  Argument @var{$arg1} and @var{$arg2} are
 256 the adjusted mmap and trim thresholds, respectively.
 257 @end deftp
 258
 259 @node Mathematical Function Probes
 260 @section Mathematical Function Probes
 261
 262 Some mathematical functions fall back to multiple precision arithmetic for
 263 some inputs to get last bit precision for their return values.  This multiple
 264 precision fallback is much slower than the default algorithms and may have a
 265 significant impact on application performance.  The systemtap probe markers
 266 described in this section may help you determine if your application calls
 267 mathematical functions with inputs that may result in multiple-precision
 268 arithmetic.
 269
 270 Unless explicitly mentioned otherwise, a precision of 1 implies 24 bits of
 271 precision in the mantissa of the multiple precision number.  Hence, a precision
 272 level of 32 implies 768 bits of precision in the mantissa.
 273
 274 @deftp Probe slowexp_p6 (double @var{$arg1}, double @var{$arg2})
 275 This probe is hit when the @code{exp} function is called with an input that
 276 results in multiple precision computation with precision 6. Argument
 277 @var{$arg1} is the input value and @var{$arg2} is the computed output.
 278 @end deftp
 279
 280 @deftp Probe slowexp_p32 (double @var{$arg1}, double @var{$arg2})
 281 This probe is hit when the @code{exp} function is called with an input that
 282 results in multiple precision computation with precision 32. Argument
 283 @var{$arg1} is the input value and @var{$arg2} is the computed output.
 284 @end deftp
 285
 286 @deftp Probe slowpow_p10 (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
 287 This probe is hit when the @code{pow} function is called with inputs that
 288 result in multiple precision computation with precision 10. Arguments
 289 @var{$arg1} and @var{$arg2} are the input values, @code{$arg3} is the value
 290 computed in the fast phase of the algorithm and @code{$arg4} is the final
 291 accurate value.
 292 @end deftp
 293
 294 @deftp Probe slowpow_p32 (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
 295 This probe is hit when the @code{pow} function is called with an input that
 296 results in multiple precision computation with precision 32. Arguments
 297 @var{$arg1} and @var{$arg2} are the input values, @code{$arg3} is the value
 298 computed in the fast phase of the algorithm and @code{$arg4} is the final
 299 accurate value.
 300 @end deftp
 301
 302 @deftp Probe slowlog (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
 303 This probe is hit when the @code{log} function is called with an input that
 304 results in multiple precision computation.  Argument @var{$arg1} is the
 305 precision with which the computation succeeded.  Argument @var{$arg2} is the
 306 input and @var{$arg3} is the computed output.
 307 @end deftp
 308
 309 @deftp Probe slowlog_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
 310 This probe is hit when the @code{log} function is called with an input that
 311 results in multiple precision computation and none of the multiple precision
 312 computations result in an accurate result.  Argument @var{$arg1} is the maximum
 313 precision  with which computations were performed.  Argument @var{$arg2} is the
 314 input and @var{$arg3} is the computed output.
 315 @end deftp
 316
 317 @deftp Probe slowatan2 (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
 318 This probe is hit when the @code{atan2} function is called with an input that
 319 results in multiple precision computation.  Argument @var{$arg1} is the
 320 precision with which computation succeeded.  Arguments @var{$arg2} and
 321 @var{$arg3} are inputs to the @code{atan2} function and @var{$arg4} is the
 322 computed result.
 323 @end deftp
 324
 325 @deftp Probe slowatan2_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
 326 This probe is hit when the @code{atan} function is called with an input that
 327 results in multiple precision computation and none of the multiple precision
 328 computations result in an accurate result.  Argument @var{$arg1} is the maximum
 329 precision  with which computations were performed.  Arguments @var{$arg2} and
 330 @var{$arg3} are inputs to the @code{atan2} function and @var{$arg4} is the
 331 computed result.
 332 @end deftp
 333
 334 @deftp Probe slowatan (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
 335 This probe is hit when the @code{atan} function is called with an input that
 336 results in multiple precision computation.  Argument @var{$arg1} is the
 337 precision with which computation succeeded.  Argument @var{$arg2} is the
 338 input to the @code{atan} function and @var{$arg3} is the computed result.
 339 @end deftp
 340
 341 @deftp Probe slowatan_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
 342 This probe is hit when the @code{atan} function is called with an input that
 343 results in multiple precision computation and none of the multiple precision
 344 computations result in an accurate result.  Argument @var{$arg1} is the maximum
 345 precision  with which computations were performed.  Argument @var{$arg2} is the
 346 input to the @code{atan} function and @var{$arg3} is the computed result.
 347 @end deftp
 348
 349 @deftp Probe slowtan (double @var{$arg1}, double @var{$arg2})
 350 This probe is hit when the @code{tan} function is called with an input that
 351 results in multiple precision computation with precision 32.  Argument
 352 @var{$arg1} is the input to the function and @var{$arg2} is the computed
 353 result.
 354 @end deftp
 355
 356 @deftp Probe slowasin (double @var{$arg1}, double @var{$arg2})
 357 This probe is hit when the @code{asin} function is called with an input that
 358 results in multiple precision computation with precision 32.  Argument
 359 @var{$arg1} is the input to the function and @var{$arg2} is the computed
 360 result.
 361 @end deftp
 362
 363 @deftp Probe slowacos (double @var{$arg1}, double @var{$arg2})
 364 This probe is hit when the @code{acos} function is called with an input that
 365 results in multiple precision computation with precision 32.  Argument
 366 @var{$arg1} is the input to the function and @var{$arg2} is the computed
 367 result.
 368 @end deftp
 369
 370 @deftp Probe slowsin (double @var{$arg1}, double @var{$arg2})
 371 This probe is hit when the @code{sin} function is called with an input that
 372 results in multiple precision computation with precision 32.  Argument
 373 @var{$arg1} is the input to the function and @var{$arg2} is the computed
 374 result.
 375 @end deftp
 376
 377 @deftp Probe slowcos (double @var{$arg1}, double @var{$arg2})
 378 This probe is hit when the @code{cos} function is called with an input that
 379 results in multiple precision computation with precision 32.  Argument
 380 @var{$arg1} is the input to the function and @var{$arg2} is the computed
 381 result.
 382 @end deftp
 383
 384 @deftp Probe slowsin_dx (double @var{$arg1}, double @var{$arg2}, double @var{$arg3})
 385 This probe is hit when the @code{sin} function is called with an input that
 386 results in multiple precision computation with precision 32.  Argument
 387 @var{$arg1} is the input to the function, @var{$arg2} is the error bound of
 388 @var{$arg1} and @var{$arg3} is the computed result.
 389 @end deftp
 390
 391 @deftp Probe slowcos_dx (double @var{$arg1}, double @var{$arg2}, double @var{$arg3})
 392 This probe is hit when the @code{cos} function is called with an input that
 393 results in multiple precision computation with precision 32.  Argument
 394 @var{$arg1} is the input to the function, @var{$arg2} is the error bound of
 395 @var{$arg1} and @var{$arg3} is the computed result.
 396 @end deftp