ceph/src/boost/libs/wave/doc/tracing_facility.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <title>The Tracing Facility</title>
   5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   6 <link href="theme/style.css" rel="stylesheet" type="text/css">
   7 </head>
   8
   9 <body>
  10 <table width="100%" border="0" cellspacing="2" background="theme/bkd2.gif">
  11   <tr>
  12     <td width="21"> <h1></h1></td>
  13     <td width="885"> <font face="Verdana, Arial, Helvetica, sans-serif"><b><font size="6">The
  14       Tracing Facility</font></b></font></td>
  15     <td width="96"><a href="http://www.boost.org"><img src="theme/wave.gif" width="93" height="68" align="right" border="0"></a></td>
  16   </tr>
  17 </table>
  18 <br>
  19 <table border="0">
  20   <tr>
  21     <td width="10"></td>
  22     <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
  23     <td width="30"><a href="wave_driver.html"><img src="theme/l_arr.gif" border="0"></a></td>
  24     <td width="30"><a href="acknowledgements.html"><img src="theme/r_arr.gif" border="0"></a></td>
  25   </tr>
  26 </table>
  27 <p>If you ever had the need to debug a macro expansion you had to discover, that
  28   your tools provide only little or no support for this task. For this reason
  29   the <i>Wave</i> library has a tracing facility, which allows to get selectively
  30   some information about the expansion of a certain macro or several macros. </p>
  31 <p>The tracing of macro expansions generates a possibly huge amount of information,
  32   so it is recommended, that you explicitely enable/disable the tracing for the
  33   macro in question only. This may be done with the help of a special, <tt>Wave</tt>
  34   specific #pragma:</p>
  35 <pre><span class="preprocessor">    #pragma</span> wave trace(enable)    <span class="comment">// enable the tracing</span>
  36     <span class="comment">// the macro expansions here will be traced</span>
  37     <span class="comment">// ...</span>
  38 <span class="preprocessor">    #pragma</span> wave trace(disable)   <span class="comment">// disable the tracing</span></pre>
  39 <p>In C99 mode or when specifying the <tt>--variadics</tt> command line option
  40   you may additionally use the <tt>operator&nbsp;_Pragma()</tt> variant to enable/disable
  41   the tracing output:</p>
  42 <pre><span class="preprocessor">    #define</span> CONCAT(x, y) \
  43         <span class="preprocessor">_Pragma</span>(<span class="string">&quot;wave trace(enable)&quot;</span>) \
  44         x \
  45         <span class="preprocessor">_Pragma</span>(<span class="string">&quot;wave trace(disable)&quot;</span>) \
  46         <span class="keyword">##</span> y</pre>
  47 <p>This way you have the possibility to enable the tracing during the expansion
  48   of a part of a macro only. In the sample shown there is traced the expansion
  49   of the macro argument <tt>'x'</tt> only. Note, that the <tt>operator _Pragma()</tt>
  50   directives expand to nothing inside the macro expansion result.</p>
  51 <p>To see, what the <tt>Wave</tt> driver generates while expanding a simple macro,
  52   let's have a look at the tracing output for the following example:</p>
  53 <pre ><span class="comment">    // test.cpp</span>
  54 <span class="preprocessor">    #define</span> X(x)          x<br><span class="preprocessor">    #define</span> Y()           2<br><span class="preprocessor">    #define</span> CONCAT_(x, y) x <span class="keyword">##</span> y
  55 <span class="preprocessor">    #define</span> CONCAT(x, y)  CONCAT_(x, y)
  56 <span class="preprocessor">    #pragma</span> wave trace(enable)
  57 <span class="comment">    // this macro expansion is to be traced</span>
  58     CONCAT(X(1), Y())     <span class="comment">// should expand to 12</span>
  59 <span class="preprocessor">    #pragma</span> wave trace(disable)</pre>
  60 <p>When preprocessed with <tt>'wave -t test.trace test.cpp'</tt> the <tt>Wave</tt>
  61   driver generates a file <tt>test.trace</tt>, which contains (without the line
  62   numbers in front of the lines):</p>
  63 <pre>  1: test.cpp:8:1: CONCAT(X(1), Y())
  64   2:   test.cpp:5:9: see macro definition: CONCAT(x, y)
  65   3:   invoked with
  66   4:   [
  67   5:     x = X(1)
  68   6:     y = Y()
  69   7:   ]
  70   8:   [
  71   9:     test.cpp:2:9: see macro definition: X(x)
  72  10:     invoked with
  73  11:     [
  74  12:       x = 1
  75  13:     ]
  76  14:     [
  77  15:       1
  78  16:       rescanning
  79  17:       [
  80  18:         1
  81  19:       ]
  82  20:     ]
  83  21:     test.cpp:3:9: see macro definition: Y()
  84  22:     [
  85  23:       2
  86  24:       rescanning
  87  25:       [
  88  26:         2
  89  27:       ]
  90  28:     ]
  91  29:     CONCAT_(1, 2)
  92  30:     rescanning
  93  31:     [
  94  32:       test.cpp:4:9: see macro definition: CONCAT_(x, y)
  95  33:       invoked with
  96  34:       [
  97  35:         x = 1
  98  36:         y = 2
  99  37:       ]
 100  38:       [
 101  39:         12
 102  40:         rescanning
 103  41:         [
 104  42:           12
 105  43:         ]
 106  44:       ]
 107  45:       12
 108  46:     ]
 109  47:   ]
 110 </pre>
 111 <p>The generated trace output is very verbose, but allows to follow every step
 112   of the actual macro expansion process. The first line in this tracing example
 113   contains the reference to the position, from where the macro expansion was initiated.
 114   Additionally the following information is contained for every single macro expansion:</p>
 115 <ul>
 116   <li>The reference to the position (line and column numbers), where the macro to expand was defined first
 117     (see lines 2, 9, 21 and 32).</li>
 118   <li>The real parameters supplied for this macro expansion (see lines 3, 10 and
 119     33), this information is traced inside the <tt>invoked with</tt> block, where
 120     the corresponding formal and actual parameters are listed.</li>
 121   <li>The expansion of the given arguments (if any and if these are defined as
 122     macros). This repeats the full tracing information for the argument macro
 123     expansion, only indended by one level. Note though, that the macro expansion
 124     of the actual arguments is traced, regardless of the fact, whether this argument
 125     is really to be inserted into the replacement list after its expansion
 126     or as it was initially supplied (see C++ Standard [16.3.1.1]: &quot;A parameter
 127     in the replacement list, unless preceded by a <tt>#</tt> or <tt>##</tt> preprocessing
 128     token or followed by a <tt>##</tt> preprocessing token, is replaced by the
 129     corresponding argument after all macros contained therein have been expanded&quot;
 130     <a href="references.html#iso_cpp">[1]</a>). </li>
 131   <li>The result of the argument substitution (see lines 15, 23, 29 and 39), i.e.
 132     the substituted replacement list.</li>
 133   <li>The rescanning process, which again includes the full subsequent macro expansion
 134     process of all found macros (see C++ Standard [16.3.4.1]: &quot;After all
 135     parameters in the replacement list have been substituted, the resulting preprocessing
 136     token sequence is rescanned with all subsequent preprocessing tokens of the
 137     source file for more macro names to replace.&quot; <a href="references.html#iso_cpp">[1]</a>).</li>
 138   <li>The result of the actual macro expansion (this is the last line inside the
 139     corresponding rescanning block - see lines 18, 26, 42 and 45).</li>
 140 </ul>
 141 <p>Every found macro to expand will add an additional indentation level inside
 142   the trace output.</p>
 143 <table border="0">
 144   <tr>
 145     <td width="10"></td>
 146     <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
 147     <td width="30"><a href="wave_driver.html"><img src="theme/l_arr.gif" border="0"></a></td>
 148     <td width="30"><a href="acknowledgements.html"><img src="theme/r_arr.gif" border="0"></a></td>
 149   </tr>
 150 </table>
 151 <hr size="1">
 152 <p class="copyright">Copyright &copy; 2003-2011 Hartmut Kaiser<br>
 153   <br>
 154 <font size="2">Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) </font> </p>
 155 <p class="copyright"><span class="updated">Last updated:
 156   <!-- #BeginDate format:fcAm1m -->Tuesday, March 21, 2006  9:25<!-- #EndDate -->
 157   </span>
 158 </p>
 159 </body>
 160 </html>
 161