mirror of
https://sourceware.org/git/glibc.git
synced 2024-11-22 13:00:06 +00:00
9d0a979e5d
This patch updates the manual and adds a new chapter to the manual, explaining types macros, constants and functions defined by ISO C11 threads.h standard. [BZ# 14092] * manual/debug.texi: Update adjacent chapter name. * manual/probes.texi: Likewise. * manual/threads.texi (ISO C Threads): New section. (POSIX Threads): Convert to a section.
382 lines
18 KiB
Plaintext
382 lines
18 KiB
Plaintext
@node Internal Probes
|
|
@c @node Internal Probes, Tunables, 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
|
|
* Non-local Goto Probes:: Probes in setjmp and longjmp
|
|
@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{}.
|
|
|
|
@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_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. A @code{memalign} probe is also used by functions
|
|
@code{posix_memalign, valloc} and @code{pvalloc}.
|
|
|
|
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.
|
|
|
|
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 allocation, and
|
|
for further allocations within that thread.
|
|
@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.
|
|
|
|
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.
|
|
@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. The argument @var{$arg1} holds a pointer to the 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 triggered 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_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.
|
|
@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.
|
|
@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
|
|
|
|
@deftp Probe memory_tunable_tcache_max_bytes (int @var{$arg1}, int @var{$arg2})
|
|
This probe is triggered when the @code{glibc.malloc.tcache_max}
|
|
tunable is set. Argument @var{$arg1} is the requested value, and
|
|
@var{$arg2} is the previous value of this tunable.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_tunable_tcache_count (int @var{$arg1}, int @var{$arg2})
|
|
This probe is triggered when the @code{glibc.malloc.tcache_count}
|
|
tunable is set. Argument @var{$arg1} is the requested value, and
|
|
@var{$arg2} is the previous value of this tunable.
|
|
@end deftp
|
|
|
|
@deftp Probe memory_tunable_tcache_unsorted_limit (int @var{$arg1}, int @var{$arg2})
|
|
This probe is triggered when the
|
|
@code{glibc.malloc.tcache_unsorted_limit} tunable is set. Argument
|
|
@var{$arg1} is the requested value, and @var{$arg2} is the previous
|
|
value of this tunable.
|
|
@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 slowatan2 (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
|
|
This probe is triggered 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 triggered 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 triggered 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 triggered 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 triggered 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
|
|
|
|
@deftp Probe slowasin (double @var{$arg1}, double @var{$arg2})
|
|
This probe is triggered when the @code{asin} 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
|
|
|
|
@deftp Probe slowacos (double @var{$arg1}, double @var{$arg2})
|
|
This probe is triggered when the @code{acos} 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
|
|
|
|
@deftp Probe slowsin (double @var{$arg1}, double @var{$arg2})
|
|
This probe is triggered when the @code{sin} 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
|
|
|
|
@deftp Probe slowcos (double @var{$arg1}, double @var{$arg2})
|
|
This probe is triggered when the @code{cos} 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
|
|
|
|
@deftp Probe slowsin_dx (double @var{$arg1}, double @var{$arg2}, double @var{$arg3})
|
|
This probe is triggered when the @code{sin} function is called with an
|
|
input that results in multiple precision computation with precision
|
|
32. Argument @var{$arg1} is the input to the function, @var{$arg2} is
|
|
the error bound of @var{$arg1} and @var{$arg3} is the computed result.
|
|
@end deftp
|
|
|
|
@deftp Probe slowcos_dx (double @var{$arg1}, double @var{$arg2}, double @var{$arg3})
|
|
This probe is triggered when the @code{cos} function is called with an
|
|
input that results in multiple precision computation with precision
|
|
32. Argument @var{$arg1} is the input to the function, @var{$arg2} is
|
|
the error bound of @var{$arg1} and @var{$arg3} is the computed result.
|
|
@end deftp
|
|
|
|
@node Non-local Goto Probes
|
|
@section Non-local Goto Probes
|
|
|
|
These probes are used to signal calls to @code{setjmp}, @code{sigsetjmp},
|
|
@code{longjmp} or @code{siglongjmp}.
|
|
|
|
@deftp Probe setjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
|
|
This probe is triggered whenever @code{setjmp} or @code{sigsetjmp} is
|
|
called. Argument @var{$arg1} is a pointer to the @code{jmp_buf}
|
|
passed as the first argument of @code{setjmp} or @code{sigsetjmp},
|
|
@var{$arg2} is the second argument of @code{sigsetjmp} or zero if this
|
|
is a call to @code{setjmp} and @var{$arg3} is a pointer to the return
|
|
address that will be stored in the @code{jmp_buf}.
|
|
@end deftp
|
|
|
|
@deftp Probe longjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
|
|
This probe is triggered whenever @code{longjmp} or @code{siglongjmp}
|
|
is called. Argument @var{$arg1} is a pointer to the @code{jmp_buf}
|
|
passed as the first argument of @code{longjmp} or @code{siglongjmp},
|
|
@var{$arg2} is the return value passed as the second argument of
|
|
@code{longjmp} or @code{siglongjmp} and @var{$arg3} is a pointer to
|
|
the return address @code{longjmp} or @code{siglongjmp} will return to.
|
|
|
|
The @code{longjmp} probe is triggered at a point where the registers
|
|
have not yet been restored to the values in the @code{jmp_buf} and
|
|
unwinding will show a call stack including the caller of
|
|
@code{longjmp} or @code{siglongjmp}.
|
|
@end deftp
|
|
|
|
@deftp Probe longjmp_target (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
|
|
This probe is triggered under the same conditions and with the same
|
|
arguments as the @code{longjmp} probe.
|
|
|
|
The @code{longjmp_target} probe is triggered at a point where the
|
|
registers have been restored to the values in the @code{jmp_buf} and
|
|
unwinding will show a call stack including the caller of @code{setjmp}
|
|
or @code{sigsetjmp}.
|
|
@end deftp
|