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