mirror of
https://sourceware.org/git/glibc.git
synced 2024-12-25 12:11:10 +00:00
10e1cf6b73
Add systemtap probes to various slow paths in libm so that application developers may use systemtap to find out if their applications are hitting these slow paths. We have added probes for pow, exp, log, tan, atan and atan2.
356 lines
18 KiB
Plaintext
356 lines
18 KiB
Plaintext
@node Internal Probes
|
|
@c @node Internal Probes, , POSIX Threads, Top
|
|
@c %MENU% Probes to monitor libc internal behavior
|
|
@chapter Internal probes
|
|
|
|
In order to aid in debugging and monitoring internal behavior,
|
|
@theglibc{} exposes nearly-zero-overhead SystemTap probes marked with
|
|
the @code{libc} provider.
|
|
|
|
These probes are not part of the @glibcadj{} stable ABI, and they are
|
|
subject to change or removal across releases. Our only promise with
|
|
regard to them is that, if we find a need to remove or modify the
|
|
arguments of a probe, the modified probe will have a different name, so
|
|
that program monitors relying on the old probe will not get unexpected
|
|
arguments.
|
|
|
|
@menu
|
|
* Memory Allocation Probes:: Probes in the memory allocation subsystem
|
|
* Mathematical Function Probes:: Probes in mathematical functions
|
|
@end menu
|
|
|
|
@node Memory Allocation Probes
|
|
@section Memory Allocation Probes
|
|
|
|
These probes are designed to signal relatively unusual situations within
|
|
the virtual memory subsystem of @theglibc{}. The location and the
|
|
availability of some probes depend on whether per-thread arenas are
|
|
enabled (the default) or disabled at the time @theglibc{} is compiled.
|
|
|
|
@deftp Probe memory_sbrk_more (void *@var{$arg1}, size_t @var{$arg2})
|
|
This probe is triggered after the main arena is extended by calling
|
|
@code{sbrk}. Argument @var{$arg1} is the additional size requested to
|
|
@code{sbrk}, and @var{$arg2} is the pointer that marks the end of the
|
|
@code{sbrk} area, returned in response to the request.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_sbrk_less (void *@var{$arg1}, size_t @var{$arg2})
|
|
This probe is triggered after the size of the main arena is decreased by
|
|
calling @code{sbrk}. Argument @var{$arg1} is the size released by
|
|
@code{sbrk} (the positive value, rather than the negative value passed
|
|
to @code{sbrk}), and @var{$arg2} is the pointer that marks the end of
|
|
the @code{sbrk} area, returned in response to the request.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_heap_new (void *@var{$arg1}, size_t @var{$arg2})
|
|
This probe is triggered after a new heap is @code{mmap}ed. Argument
|
|
@var{$arg1} is a pointer to the base of the memory area, where the
|
|
@code{heap_info} data structure is held, and @var{$arg2} is the size of
|
|
the heap.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_heap_free (void *@var{$arg1}, size_t @var{$arg2})
|
|
This probe is triggered @emph{before} (unlike the other sbrk and heap
|
|
probes) a heap is completely removed via @code{munmap}. Argument
|
|
@var{$arg1} is a pointer to the heap, and @var{$arg2} is the size of the
|
|
heap.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_heap_more (void *@var{$arg1}, size_t @var{$arg2})
|
|
This probe is triggered after a trailing portion of an @code{mmap}ed
|
|
heap is extended. Argument @var{$arg1} is a pointer to the heap, and
|
|
@var{$arg2} is the new size of the heap.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_heap_less (void *@var{$arg1}, size_t @var{$arg2})
|
|
This probe is triggered after a trailing portion of an @code{mmap}ed
|
|
heap is released. Argument @var{$arg1} is a pointer to the heap, and
|
|
@var{$arg2} is the new size of the heap.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_malloc_retry (size_t @var{$arg1})
|
|
@deftpx Probe memory_realloc_retry (size_t @var{$arg1}, void *@var{$arg2})
|
|
@deftpx Probe memory_memalign_retry (size_t @var{$arg1}, size_t @var{$arg2})
|
|
@deftpx Probe memory_valloc_retry (size_t @var{$arg1})
|
|
@deftpx Probe memory_pvalloc_retry (size_t @var{$arg1})
|
|
@deftpx Probe memory_calloc_retry (size_t @var{$arg1})
|
|
These probes are triggered when the corresponding functions fail to
|
|
obtain the requested amount of memory from the arena in use, before they
|
|
call @code{arena_get_retry} to select an alternate arena in which to
|
|
retry the allocation. Argument @var{$arg1} is the amount of memory
|
|
requested by the user; in the @code{calloc} case, that is the total size
|
|
computed from both function arguments. In the @code{realloc} case,
|
|
@var{$arg2} is the pointer to the memory area being resized. In the
|
|
@code{memalign} case, @var{$arg2} is the alignment to be used for the
|
|
request, which may be stricter than the value passed to the
|
|
@code{memalign} function.
|
|
|
|
Note that the argument order does @emph{not} match that of the
|
|
corresponding two-argument functions, so that in all of these probes the
|
|
user-requested allocation size is in @var{$arg1}.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_arena_retry (size_t @var{$arg1}, void *@var{$arg2})
|
|
This probe is triggered within @code{arena_get_retry} (the function
|
|
called to select the alternate arena in which to retry an allocation
|
|
that failed on the first attempt), before the selection of an alternate
|
|
arena. This probe is redundant, but much easier to use when it's not
|
|
important to determine which of the various memory allocation functions
|
|
is failing to allocate on the first try. Argument @var{$arg1} is the
|
|
same as in the function-specific probes, except for extra room for
|
|
padding introduced by functions that have to ensure stricter alignment.
|
|
Argument @var{$arg2} is the arena in which allocation failed.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_arena_new (void *@var{$arg1}, size_t @var{$arg2})
|
|
This probe is triggered when @code{malloc} allocates and initializes an
|
|
additional arena (not the main arena), but before the arena is assigned
|
|
to the running thread or inserted into the internal linked list of
|
|
arenas. The arena's @code{malloc_state} internal data structure is
|
|
located at @var{$arg1}, within a newly-allocated heap big enough to hold
|
|
at least @var{$arg2} bytes.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_arena_reuse (void *@var{$arg1}, void *@var{$arg2})
|
|
This probe is triggered when @code{malloc} has just selected an existing
|
|
arena to reuse, and (temporarily) reserved it for exclusive use.
|
|
Argument @var{$arg1} is a pointer to the newly-selected arena, and
|
|
@var{$arg2} is a pointer to the arena previously used by that thread.
|
|
|
|
When per-thread arenas are enabled, this occurs within
|
|
@code{reused_arena}, right after the mutex mentioned in probe
|
|
@code{memory_arena_reuse_wait} is acquired; argument @var{$arg1} will
|
|
point to the same arena. In this configuration, this will usually only
|
|
occur once per thread. The exception is when a thread first selected
|
|
the main arena, but a subsequent allocation from it fails: then, and
|
|
only then, may we switch to another arena to retry that allocations, and
|
|
for further allocations within that thread.
|
|
|
|
When per-thread arenas are disabled, this occurs within
|
|
@code{arena_get2}, whenever the mutex for the previously-selected arena
|
|
cannot be immediately acquired.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_arena_reuse_wait (void *@var{$arg1}, void *@var{$arg2}, void *@var{$arg3})
|
|
This probe is triggered when @code{malloc} is about to wait for an arena
|
|
to become available for reuse. Argument @var{$arg1} holds a pointer to
|
|
the mutex the thread is going to wait on, @var{$arg2} is a pointer to a
|
|
newly-chosen arena to be reused, and @var{$arg3} is a pointer to the
|
|
arena previously used by that thread.
|
|
|
|
When per-thread arenas are enabled, this occurs within
|
|
@code{reused_arena}, when a thread first tries to allocate memory or
|
|
needs a retry after a failure to allocate from the main arena, there
|
|
isn't any free arena, the maximum number of arenas has been reached, and
|
|
an existing arena was chosen for reuse, but its mutex could not be
|
|
immediately acquired. The mutex in @var{$arg1} is the mutex of the
|
|
selected arena.
|
|
|
|
When per-thread arenas are disabled, this occurs within
|
|
@code{arena_get2}, when a thread first tries to allocate memory or the
|
|
mutex of the arena it previously used could not be immediately acquired,
|
|
and none of the existing arenas could be immediately reserved for
|
|
exclusive use. The mutex in @var{$arg1} is that of the list of arenas,
|
|
and since the arena won't have been selected yet, @var{$arg2} will be
|
|
@code{NULL}.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_arena_reuse_free_list (void *@var{$arg1})
|
|
This probe is triggered when @code{malloc} has chosen an arena that is
|
|
in the free list for use by a thread, within the @code{get_free_list}
|
|
function. This probe is only available when @code{malloc} is configured
|
|
to use per-thread arenas. The argument @var{$arg1} holds a pointer to
|
|
the selected arena.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_arena_reuse_realloc (void *@var{$arg1})
|
|
This probe is triggered within @code{realloc}, as the arena of the
|
|
current thread is changed to match that in which the given address was
|
|
allocated. This probe is @emph{not} available when @code{malloc} is
|
|
configured to use per-thread arenas. The argument @var{$arg1} holds a
|
|
pointer to the newly-selected arena.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_mallopt (int @var{$arg1}, int @var{$arg2})
|
|
This probe is triggered when function @code{mallopt} is called to change
|
|
@code{malloc} internal configuration parameters, before any change to
|
|
the parameters is made. The arguments @var{$arg1} and @var{$arg2} are
|
|
the ones passed to the @code{mallopt} function.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_mallopt_mxfast (int @var{$arg1}, int @var{$arg2})
|
|
This probe is triggered shortly after the @code{memory_mallopt} probe,
|
|
when the parameter to be changed is @code{M_MXFAST}, and the requested
|
|
value is in an acceptable range. Argument @var{$arg1} is the requested
|
|
value, and @var{$arg2} is the previous value of this @code{malloc}
|
|
parameter.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_mallopt_trim_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
|
|
This probe is triggere shortly after the @code{memory_mallopt} probe,
|
|
when the parameter to be changed is @code{M_TRIM_THRESHOLD}. Argument
|
|
@var{$arg1} is the requested value, @var{$arg2} is the previous value of
|
|
this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
|
|
threshold adjustment was already disabled.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_mallopt_top_pad (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
|
|
This probe is triggered shortly after the @code{memory_mallopt} probe,
|
|
when the parameter to be changed is @code{M_TOP_PAD}. Argument
|
|
@var{$arg1} is the requested value, @var{$arg2} is the previous value of
|
|
this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
|
|
threshold adjustment was already disabled.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_mallopt_mmap_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
|
|
This probe is triggered shortly after the @code{memory_mallopt} probe,
|
|
when the parameter to be changed is @code{M_MMAP_THRESHOLD}, and the
|
|
requested value is in an acceptable range. Argument @var{$arg1} is the
|
|
requested value, @var{$arg2} is the previous value of this @code{malloc}
|
|
parameter, and @var{$arg3} is nonzero if dynamic threshold adjustment
|
|
was already disabled.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_mallopt_mmap_max (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
|
|
This probe is triggered shortly after the @code{memory_mallopt} probe,
|
|
when the parameter to be changed is @code{M_MMAP_MAX}. Argument
|
|
@var{$arg1} is the requested value, @var{$arg2} is the previous value of
|
|
this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
|
|
threshold adjustment was already disabled.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_mallopt_check_action (int @var{$arg1}, int @var{$arg2})
|
|
This probe is triggered shortly after the @code{memory_mallopt} probe,
|
|
when the parameter to be changed is @code{M_CHECK_ACTION}. Argument
|
|
@var{$arg1} is the requested value, and @var{$arg2} is the previous
|
|
value of this @code{malloc} parameter.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_mallopt_perturb (int @var{$arg1}, int @var{$arg2})
|
|
This probe is triggered shortly after the @code{memory_mallopt} probe,
|
|
when the parameter to be changed is @code{M_PERTURB}. Argument
|
|
@var{$arg1} is the requested value, and @var{$arg2} is the previous
|
|
value of this @code{malloc} parameter.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_mallopt_arena_test (int @var{$arg1}, int @var{$arg2})
|
|
This probe is triggered shortly after the @code{memory_mallopt} probe,
|
|
when the parameter to be changed is @code{M_ARENA_TEST}, and the
|
|
requested value is in an acceptable range. Argument @var{$arg1} is the
|
|
requested value, and @var{$arg2} is the previous value of this
|
|
@code{malloc} parameter. This probe is only available when per-thread
|
|
arenas are enabled.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_mallopt_arena_max (int @var{$arg1}, int @var{$arg2})
|
|
This probe is triggered shortly after the @code{memory_mallopt} probe,
|
|
when the parameter to be changed is @code{M_ARENA_MAX}, and the
|
|
requested value is in an acceptable range. Argument @var{$arg1} is the
|
|
requested value, and @var{$arg2} is the previous value of this
|
|
@code{malloc} parameter. This probe is only available when per-thread
|
|
arenas are enabled.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_mallopt_free_dyn_thresholds (int @var{$arg1}, int @var{$arg2})
|
|
This probe is triggered when function @code{free} decides to adjust the
|
|
dynamic brk/mmap thresholds. Argument @var{$arg1} and @var{$arg2} are
|
|
the adjusted mmap and trim thresholds, respectively.
|
|
@end deftp
|
|
|
|
@node Mathematical Function Probes
|
|
@section Mathematical Function Probes
|
|
|
|
Some mathematical functions fall back to multiple precision arithmetic for
|
|
some inputs to get last bit precision for their return values. This multiple
|
|
precision fallback is much slower than the default algorithms and may have a
|
|
significant impact on application performance. The systemtap probe markers
|
|
described in this section may help you determine if your application calls
|
|
mathematical functions with inputs that may result in multiple-precision
|
|
arithmetic.
|
|
|
|
Unless explicitly mentioned otherwise, a precision of 1 implies 24 bits of
|
|
precision in the mantissa of the multiple precision number. Hence, a precision
|
|
level of 32 implies 768 bits of precision in the mantissa.
|
|
|
|
@deftp Probe slowexp_p6 (double @var{$arg1}, double @var{$arg2})
|
|
This probe is hit when the @code{exp} function is called with an input that
|
|
results in multiple precision computation with precision 6. Argument
|
|
@var{$arg1} is the input value and @var{$arg2} is the computed output.
|
|
@end deftp
|
|
|
|
@deftp Probe slowexp_p32 (double @var{$arg1}, double @var{$arg2})
|
|
This probe is hit when the @code{exp} function is called with an input that
|
|
results in multiple precision computation with precision 32. Argument
|
|
@var{$arg1} is the input value and @var{$arg2} is the computed output.
|
|
@end deftp
|
|
|
|
@deftp Probe slowpow_p10 (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
|
|
This probe is hit when the @code{pow} function is called with inputs that
|
|
result in multiple precision computation with precision 10. Arguments
|
|
@var{$arg1} and @var{$arg2} are the input values, @code{$arg3} is the value
|
|
computed in the fast phase of the algorithm and @code{$arg4} is the final
|
|
accurate value.
|
|
@end deftp
|
|
|
|
@deftp Probe slowpow_p32 (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
|
|
This probe is hit when the @code{pow} function is called with an input that
|
|
results in multiple precision computation with precision 32. Arguments
|
|
@var{$arg1} and @var{$arg2} are the input values, @code{$arg3} is the value
|
|
computed in the fast phase of the algorithm and @code{$arg4} is the final
|
|
accurate value.
|
|
@end deftp
|
|
|
|
@deftp Probe slowlog (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
|
|
This probe is hit when the @code{log} function is called with an input that
|
|
results in multiple precision computation. Argument @var{$arg1} is the
|
|
precision with which the computation succeeded. Argument @var{$arg2} is the
|
|
input and @var{$arg3} is the computed output.
|
|
@end deftp
|
|
|
|
@deftp Probe slowlog_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
|
|
This probe is hit when the @code{log} function is called with an input that
|
|
results in multiple precision computation and none of the multiple precision
|
|
computations result in an accurate result. Argument @var{$arg1} is the maximum
|
|
precision with which computations were performed. Argument @var{$arg2} is the
|
|
input and @var{$arg3} is the computed output.
|
|
@end deftp
|
|
|
|
@deftp Probe slowatan2 (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
|
|
This probe is hit when the @code{atan2} function is called with an input that
|
|
results in multiple precision computation. Argument @var{$arg1} is the
|
|
precision with which computation succeeded. Arguments @var{$arg2} and
|
|
@var{$arg3} are inputs to the @code{atan2} function and @var{$arg4} is the
|
|
computed result.
|
|
@end deftp
|
|
|
|
@deftp Probe slowatan2_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
|
|
This probe is hit when the @code{atan} function is called with an input that
|
|
results in multiple precision computation and none of the multiple precision
|
|
computations result in an accurate result. Argument @var{$arg1} is the maximum
|
|
precision with which computations were performed. Arguments @var{$arg2} and
|
|
@var{$arg3} are inputs to the @code{atan2} function and @var{$arg4} is the
|
|
computed result.
|
|
@end deftp
|
|
|
|
@deftp Probe slowatan (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
|
|
This probe is hit when the @code{atan} function is called with an input that
|
|
results in multiple precision computation. Argument @var{$arg1} is the
|
|
precision with which computation succeeded. Argument @var{$arg2} is the
|
|
input to the @code{atan} function and @var{$arg3} is the computed result.
|
|
@end deftp
|
|
|
|
@deftp Probe slowatan_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
|
|
This probe is hit when the @code{atan} function is called with an input that
|
|
results in multiple precision computation and none of the multiple precision
|
|
computations result in an accurate result. Argument @var{$arg1} is the maximum
|
|
precision with which computations were performed. Argument @var{$arg2} is the
|
|
input to the @code{atan} function and @var{$arg3} is the computed result.
|
|
@end deftp
|
|
|
|
@deftp Probe slowtan (double @var{$arg1}, double @var{$arg2})
|
|
This probe is hit when the @code{tan} function is called with an input that
|
|
results in multiple precision computation with precision 32. Argument
|
|
@var{$arg1} is the input to the function and @var{$arg2} is the computed
|
|
result.
|
|
@end deftp
|