Developer Information
Prev | Chapter 19. Profile Mode | Next

## Developer Information

### Big Picture

The profile mode headers are included with `-D_GLIBCXX_PROFILE` through preprocessor directives in `include/std/*`.

Instrumented implementations are provided in `include/profile/*`. All instrumentation hooks are macros defined in `include/profile/profiler.h`.

All the implementation of the instrumentation hooks is in `include/profile/impl/*`. Although all the code gets included, thus is publicly visible, only a small number of functions are called from outside this directory. All calls to hook implementations must be done through macros defined in `profiler.h`. The macro must ensure (1) that the call is guarded against reentrance and (2) that the call can be turned off at compile time using a `-D_GLIBCXX_PROFILE_...` compiler option.

### How To Add A Diagnostic

Let's say the diagnostic name is "magic".

If you need to instrument a header not already under `include/profile/*`, first edit the corresponding header under `include/std/` and add a preprocessor directive such as the one in `include/std/vector`:

    #ifdef _GLIBCXX_PROFILE
    # include <profile/vector>
    #endif

If the file you need to instrument is not yet under `include/profile/`, make a copy of the one in `include/debug`, or the main implementation. You'll need to include the main implementation and inherit the classes you want to instrument. Then define the methods you want to instrument, define the instrumentation hooks and add calls to them. Look at `include/profile/vector` for an example.

Add macros for the instrumentation hooks in `include/profile/impl/profiler.h`. Hook names must start with `__profcxx_`. Make sure they transform in no code with `-D_NO_GLIBCXX_PROFILE_MAGIC`. Make sure all calls to any method in namespace `__gnu_profile` is protected against reentrance using macro `_GLIBCXX_PROFILE_REENTRANCE_GUARD`. All names of methods in namespace `__gnu_profile` called from `profiler.h` must start with `__trace_magic_`.

Add the implementation of the diagnostic.

- Create new file `include/profile/impl/profiler_magic.h`.

- Define class `__magic_info: public __object_info_base`. This is the representation of a line in the object table. The `__merge` method is used to aggregate information across all dynamic instances created at the same call context. The `__magnitude` must return the estimation of the benefit as a number of small operations, e.g., number of words copied. The `__write` method is used to produce the raw trace. The `__advice` method is used to produce the advice string.

- Define class `__magic_stack_info: public __magic_info`. This defines the content of a line in the stack table.

- Define class `__trace_magic: public __trace_base<__magic_info, __magic_stack_info>`. It defines the content of the trace associated with this diagnostic.

Add initialization and reporting calls in `include/profile/impl/profiler_trace.h`. Use `__trace_vector_to_list` as an example.

Add documentation in file `doc/xml/manual/profile_mode.xml`.

Prev | Up | Next
Implementation Issues | Home | Diagnostics