Internal probes
***************

In order to aid in debugging and monitoring internal behavior, theglibc exposes nearly-zero-overhead SystemTap probes marked with the 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.

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.

 -- Probe: memory_arena_new (void *$ARG1, size_t $ARG2)
     This probe is triggered when 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 malloc_state internal data structure is located at $ARG1, within a newly-allocated heap big enough to hold at least $ARG2 bytes.

 -- Probe: memory_arena_reuse (void *$ARG1, void *$ARG2)
     This probe is triggered when malloc has just selected an existing arena to reuse, and (temporarily) reserved it for exclusive use. Argument $ARG1 is a pointer to the newly-selected arena, and $ARG2 is a pointer to the arena previously used by that thread.

     When per-thread arenas are enabled, this occurs within reused_arena, right after the mutex mentioned in probe memory_arena_reuse_wait is acquired; argument $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 arena_get2, whenever the mutex for the previously-selected arena cannot be immediately acquired.

 -- Probe: memory_arena_reuse_wait (void *$ARG1, void *$ARG2, void *$ARG3)
     This probe is triggered when malloc is about to wait for an arena to become available for reuse.  Argument $ARG1 holds a pointer to the mutex the thread is going to wait on, $ARG2 is a pointer to a newly-chosen arena to be reused, and $ARG3 is a pointer to the arena previously used by that thread.

     When per-thread arenas are enabled, this occurs within 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 $ARG1 is the mutex of the selected arena.

     When per-thread arenas are disabled, this occurs within 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 $ARG1 is that of the list of arenas, and since the arena won't have been selected yet, $ARG2 will be NULL.

 -- Probe: memory_arena_reuse_free_list (void *$ARG1)
     This probe is triggered when malloc has chosen an arena that is in the free list for use by a thread, within the get_free_list function.  This probe is only available when malloc is configured to use per-thread arenas.  The argument $ARG1 holds a pointer to the selected arena.

 -- Probe: memory_arena_reuse_realloc (void *$ARG1)
     This probe is triggered within realloc, as the arena of the current thread is changed to match that in which the given address was allocated.  This probe is not available when malloc is configured to use per-thread arenas.  The argument $ARG1 holds a pointer to the newly-selected arena.

 -- Probe: memory_mallopt (int $ARG1, int $ARG2)
     This probe is triggered when function mallopt is called to change malloc internal configuration parameters, before any change to the parameters is made.  The arguments $ARG1 and $ARG2 are the ones passed to the mallopt function.

 -- Probe: memory_mallopt_mxfast (int $ARG1, int $ARG2)
     This probe is triggered shortly after the memory_mallopt probe, when the parameter to be changed is M_MXFAST, and the requested value is in an acceptable range.  Argument $ARG1 is the requested value, and $ARG2 is the previous value of this malloc parameter.

 -- Probe: memory_mallopt_trim_threshold (int $ARG1, int $ARG2, int $ARG3)
     This probe is triggere shortly after the memory_mallopt probe, when the parameter to be changed is M_TRIM_THRESHOLD.  Argument $ARG1 is the requested value, $ARG2 is the previous value of this malloc parameter, and $ARG3 is nonzero if dynamic threshold adjustment was already disabled.

 -- Probe: memory_mallopt_top_pad (int $ARG1, int $ARG2, int $ARG3)
     This probe is triggered shortly after the memory_mallopt probe, when the parameter to be changed is M_TOP_PAD.  Argument $ARG1 is the requested value, $ARG2 is the previous value of this malloc parameter, and $ARG3 is nonzero if dynamic threshold adjustment was already disabled.

 -- Probe: memory_mallopt_mmap_threshold (int $ARG1, int $ARG2, int $ARG3)
     This probe is triggered shortly after the memory_mallopt probe, when the parameter to be changed is M_MMAP_THRESHOLD, and the requested value is in an acceptable range.  Argument $ARG1 is the requested value, $ARG2 is the previous value of this malloc parameter, and $ARG3 is nonzero if dynamic threshold adjustment was already disabled.

 -- Probe: memory_mallopt_mmap_max (int $ARG1, int $ARG2, int $ARG3)
     This probe is triggered shortly after the memory_mallopt probe, when the parameter to be changed is M_MMAP_MAX.  Argument $ARG1 is the requested value, $ARG2 is the previous value of this malloc parameter, and $ARG3 is nonzero if dynamic threshold adjustment was already disabled.

 -- Probe: memory_mallopt_check_action (int $ARG1, int $ARG2)
     This probe is triggered shortly after the memory_mallopt probe, when the parameter to be changed is M_CHECK_ACTION.  Argument $ARG1 is the requested value, and $ARG2 is the previous value of this malloc parameter.

 -- Probe: memory_mallopt_perturb (int $ARG1, int $ARG2)
     This probe is triggered shortly after the memory_mallopt probe, when the parameter to be changed is M_PERTURB.  Argument $ARG1 is the requested value, and $ARG2 is the previous value of this malloc parameter.

 -- Probe: memory_mallopt_arena_test (int $ARG1, int $ARG2)
     This probe is triggered shortly after the memory_mallopt probe, when the parameter to be changed is M_ARENA_TEST, and the requested value is in an acceptable range.  Argument $ARG1 is the requested value, and $ARG2 is the previous value of this malloc parameter.  This probe is only available when per-thread arenas are enabled.

 -- Probe: memory_mallopt_arena_max (int $ARG1, int $ARG2)
     This probe is triggered shortly after the memory_mallopt probe, when the parameter to be changed is M_ARENA_MAX, and the requested value is in an acceptable range.  Argument $ARG1 is the requested value, and $ARG2 is the previous value of this malloc parameter.  This probe is only available when per-thread arenas are enabled.

 -- Probe: memory_mallopt_free_dyn_thresholds (int $ARG1, int $ARG2)
     This probe is triggered when function free decides to adjust the dynamic brk/mmap thresholds.  Argument $ARG1 and $ARG2 are the adjusted mmap and trim thresholds, respectively.