Developer Information

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.

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_GLBICXX_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.

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.