libstdc++-v3/doc/html/manual/bk01pt03ch19s06.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Developer Information</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><meta name="keywords" content="
   2       C++
   3     ,
   4       library
   5     ,
   6       profile
   7     "><meta name="keywords" content="
   8       ISO C++
   9     ,
  10       library
  11     "><meta name="keywords" content="
  12       ISO C++
  13     ,
  14       runtime
  15     ,
  16       library
  17     "><link rel="home" href="../index.html" title="The GNU C++ Library"><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode"><link rel="prev" href="bk01pt03ch19s05.html" title="Implementation Issues"><link rel="next" href="bk01pt03ch19s07.html" title="Diagnostics"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Developer Information</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt03ch19s05.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch19s07.html">Next</a></td></tr></table><hr></div><div class="section" title="Developer Information"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="manual.ext.profile_mode.developer"></a>Developer Information</h2></div></div></div><div class="section" title="Big Picture"><div class="titlepage"><div><div><h3 class="title"><a name="manual.ext.profile_mode.developer.bigpic"></a>Big Picture</h3></div></div></div><p>The profile mode headers are included with
  18    <code class="code">-D_GLIBCXX_PROFILE</code> through preprocessor directives in
  19    <code class="code">include/std/*</code>.
  20   </p><p>Instrumented implementations are provided in
  21    <code class="code">include/profile/*</code>.  All instrumentation hooks are macros
  22    defined in <code class="code">include/profile/profiler.h</code>.
  23   </p><p>All the implementation of the instrumentation hooks is in
  24    <code class="code">include/profile/impl/*</code>.  Although all the code gets included,
  25    thus is publicly visible, only a small number of functions are called from
  26    outside this directory.  All calls to hook implementations must be
  27    done through macros defined in <code class="code">profiler.h</code>.  The macro
  28    must ensure (1) that the call is guarded against reentrance and
  29    (2) that the call can be turned off at compile time using a
  30    <code class="code">-D_GLIBCXX_PROFILE_...</code> compiler option.
  31   </p></div><div class="section" title="How To Add A Diagnostic"><div class="titlepage"><div><div><h3 class="title"><a name="manual.ext.profile_mode.developer.howto"></a>How To Add A Diagnostic</h3></div></div></div><p>Let's say the diagnostic name is "magic".
  32   </p><p>If you need to instrument a header not already under
  33    <code class="code">include/profile/*</code>, first edit the corresponding header
  34    under <code class="code">include/std/</code> and add a preprocessor directive such
  35    as the one in <code class="code">include/std/vector</code>:
  36 </p><pre class="programlisting">
  37 #ifdef _GLIBCXX_PROFILE
  38 # include &lt;profile/vector&gt;
  39 #endif
  40 </pre><p>
  41   </p><p>If the file you need to instrument is not yet under
  42    <code class="code">include/profile/</code>, make a copy of the one in
  43    <code class="code">include/debug</code>, or the main implementation.
  44    You'll need to include the main implementation and inherit the classes
  45    you want to instrument.  Then define the methods you want to instrument,
  46    define the instrumentation hooks and add calls to them.
  47    Look at <code class="code">include/profile/vector</code> for an example.
  48   </p><p>Add macros for the instrumentation hooks in
  49    <code class="code">include/profile/impl/profiler.h</code>.
  50    Hook names must start with <code class="code">__profcxx_</code>.
  51    Make sure they transform
  52    in no code with <code class="code">-D_NO_GLBICXX_PROFILE_MAGIC</code>.
  53    Make sure all calls to any method in namespace <code class="code">__gnu_profile</code>
  54    is protected against reentrance using macro
  55    <code class="code">_GLIBCXX_PROFILE_REENTRANCE_GUARD</code>.
  56    All names of methods in namespace <code class="code">__gnu_profile</code> called from
  57    <code class="code">profiler.h</code> must start with <code class="code">__trace_magic_</code>.
  58   </p><p>Add the implementation of the diagnostic.
  59    </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
  60       Create new file <code class="code">include/profile/impl/profiler_magic.h</code>.
  61      </p></li><li class="listitem"><p>
  62       Define class <code class="code">__magic_info: public __object_info_base</code>.
  63       This is the representation of a line in the object table.
  64       The <code class="code">__merge</code> method is used to aggregate information
  65       across all dynamic instances created at the same call context.
  66       The <code class="code">__magnitude</code> must return the estimation of the benefit
  67       as a number of small operations, e.g., number of words copied.
  68       The <code class="code">__write</code> method is used to produce the raw trace.
  69       The <code class="code">__advice</code> method is used to produce the advice string.
  70      </p></li><li class="listitem"><p>
  71       Define class <code class="code">__magic_stack_info: public __magic_info</code>.
  72       This defines the content of a line in the stack table.
  73      </p></li><li class="listitem"><p>
  74       Define class <code class="code">__trace_magic: public __trace_base&lt;__magic_info,
  75       __magic_stack_info&gt;</code>.
  76       It defines the content of the trace associated with this diagnostic.
  77      </p></li></ul></div><p>
  78   </p><p>Add initialization and reporting calls in
  79    <code class="code">include/profile/impl/profiler_trace.h</code>.  Use
  80    <code class="code">__trace_vector_to_list</code> as an example.
  81   </p><p>Add documentation in file <code class="code">doc/xml/manual/profile_mode.xml</code>.
  82   </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch19s05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt03ch19s07.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Implementation Issues </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Diagnostics</td></tr></table></div></body></html>