Subject: [Boost-commit] svn:boost r55566 - in trunk/libs/spirit/repository/doc: html html/spirit_repository html/spirit_repository/karma_components/directives html/spirit_repository/qi_components/directives html/spirit_repository/qi_components/nonterminal html/spirit_repository/qi_components/primitive qi
From: frabar666_at_[hidden]
Date: 2009-08-13 09:00:22
Author: fbarel
Date: 2009-08-13 09:00:20 EDT (Thu, 13 Aug 2009)
New Revision: 55566
URL: http://svn.boost.org/trac/boost/changeset/55566
Log:
Spirit: add performance section to subrules doc
Text files modified:
trunk/libs/spirit/repository/doc/html/index.html | 4
trunk/libs/spirit/repository/doc/html/spirit_repository/karma_components/directives/karma_confix_generator.html | 18 +-
trunk/libs/spirit/repository/doc/html/spirit_repository/preface.html | 8
trunk/libs/spirit/repository/doc/html/spirit_repository/qi_components/directives/confix.html | 18 +-
trunk/libs/spirit/repository/doc/html/spirit_repository/qi_components/directives/distinct.html | 16 +-
trunk/libs/spirit/repository/doc/html/spirit_repository/qi_components/nonterminal/subrule.html | 266 ++++++++++++++++++++++++++++++++++++---
trunk/libs/spirit/repository/doc/html/spirit_repository/qi_components/primitive/flush_multi_pass.html | 16 +-
trunk/libs/spirit/repository/doc/qi/subrule.qbk | 43 +++++-
8 files changed, 320 insertions(+), 69 deletions(-)
Modified: trunk/libs/spirit/repository/doc/html/index.html
==============================================================================
--- trunk/libs/spirit/repository/doc/html/index.html (original)
+++ trunk/libs/spirit/repository/doc/html/index.html 2009-08-13 09:00:20 EDT (Thu, 13 Aug 2009)
@@ -34,7 +34,7 @@
<div><p class="copyright">Copyright © 2001-2009 Joel
de Guzman, Hartmut Kaiser</p></div>
<div><div class="legalnotice" title="Legal Notice">
-<a name="id1128913"></a><p>
+<a name="id2646821"></a><p>
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)
</p>
@@ -76,7 +76,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: August 12, 2009 at 22:56:46 GMT</small></p></td>
+<td align="left"><p><small>Last revised: August 13, 2009 at 12:57:35 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>
Modified: trunk/libs/spirit/repository/doc/html/spirit_repository/karma_components/directives/karma_confix_generator.html
==============================================================================
--- trunk/libs/spirit/repository/doc/html/spirit_repository/karma_components/directives/karma_confix_generator.html (original)
+++ trunk/libs/spirit/repository/doc/html/spirit_repository/karma_components/directives/karma_confix_generator.html 2009-08-13 09:00:20 EDT (Thu, 13 Aug 2009)
@@ -27,7 +27,7 @@
Confix Generator</a>
</h4></div></div></div>
<a name="spirit_repository.karma_components.directives.karma_confix_generator.description"></a><h6>
-<a name="id1144120"></a>
+<a name="id2706694"></a>
<a class="link" href="karma_confix_generator.html#spirit_repository.karma_components.directives.karma_confix_generator.description">Description</a>
</h6>
<p>
@@ -92,20 +92,20 @@
tag using a simple: <code class="computeroutput"><span class="identifier">ol</span><span class="special">[</span><span class="string">"Some text"</span><span class="special">]</span></code> (which results in <code class="computeroutput"><span class="special"><</span><span class="identifier">ol</span><span class="special">></span><span class="identifier">Some</span> <span class="identifier">text</span><span class="special"></</span><span class="identifier">ol</span><span class="special">></span></code>).
</p>
<a name="spirit_repository.karma_components.directives.karma_confix_generator.header"></a><h6>
-<a name="id1145017"></a>
+<a name="id2707830"></a>
<a class="link" href="karma_confix_generator.html#spirit_repository.karma_components.directives.karma_confix_generator.header">Header</a>
</h6>
<pre class="programlisting"><span class="comment">// forwards to <boost/spirit/repository/home/karma/directive/confix.hpp>
</span><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">repository</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">karma_confix</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
</pre>
<a name="spirit_repository.karma_components.directives.karma_confix_generator.synopsis"></a><h6>
-<a name="id1145090"></a>
+<a name="id2707933"></a>
<a class="link" href="karma_confix_generator.html#spirit_repository.karma_components.directives.karma_confix_generator.synopsis">Synopsis</a>
</h6>
<pre class="programlisting"><span class="identifier">confix</span><span class="special">(</span><span class="identifier">prefix</span><span class="special">,</span> <span class="identifier">suffix</span><span class="special">)[</span><span class="identifier">subject</span><span class="special">]</span>
</pre>
<a name="spirit_repository.karma_components.directives.karma_confix_generator.parameters"></a><h6>
-<a name="id1145138"></a>
+<a name="id2707998"></a>
<a class="link" href="karma_confix_generator.html#spirit_repository.karma_components.directives.karma_confix_generator.parameters">Parameters</a>
</h6>
<div class="informaltable"><table class="table">
@@ -174,7 +174,7 @@
All three parameters can be arbitrary complex generators themselves.
</p>
<a name="spirit_repository.karma_components.directives.karma_confix_generator.attribute"></a><h6>
-<a name="id1145296"></a>
+<a name="id2708199"></a>
<a class="link" href="karma_confix_generator.html#spirit_repository.karma_components.directives.karma_confix_generator.attribute">Attribute</a>
</h6>
<p>
@@ -201,7 +201,7 @@
</p></td></tr>
</table></div>
<a name="spirit_repository.karma_components.directives.karma_confix_generator.example"></a><h6>
-<a name="id1145471"></a>
+<a name="id2708439"></a>
<a class="link" href="karma_confix_generator.html#spirit_repository.karma_components.directives.karma_confix_generator.example">Example</a>
</h6>
<p>
@@ -210,7 +210,7 @@
styles and a function prototype (for the full example code see here: confix.cpp)
</p>
<a name="spirit_repository.karma_components.directives.karma_confix_generator.prerequisites"></a><h6>
-<a name="id1145501"></a>
+<a name="id2708487"></a>
<a class="link" href="karma_confix_generator.html#spirit_repository.karma_components.directives.karma_confix_generator.prerequisites">Prerequisites</a>
</h6>
<p>
@@ -248,7 +248,7 @@
<p>
</p>
<a name="spirit_repository.karma_components.directives.karma_confix_generator.generating_different_comment_styles"></a><h6>
-<a name="id1145745"></a>
+<a name="id2708799"></a>
<a class="link" href="karma_confix_generator.html#spirit_repository.karma_components.directives.karma_confix_generator.generating_different_comment_styles">Generating
Different Comment Styles</a>
</h6>
@@ -300,7 +300,7 @@
*/</span> </code>.
</p>
<a name="spirit_repository.karma_components.directives.karma_confix_generator.generating_a_function_prototype"></a><h6>
-<a name="id1146046"></a>
+<a name="id2709182"></a>
<a class="link" href="karma_confix_generator.html#spirit_repository.karma_components.directives.karma_confix_generator.generating_a_function_prototype">Generating
a Function Prototype</a>
</h6>
Modified: trunk/libs/spirit/repository/doc/html/spirit_repository/preface.html
==============================================================================
--- trunk/libs/spirit/repository/doc/html/spirit_repository/preface.html (original)
+++ trunk/libs/spirit/repository/doc/html/spirit_repository/preface.html 2009-08-13 09:00:20 EDT (Thu, 13 Aug 2009)
@@ -27,7 +27,7 @@
<a name="spirit_repository.preface"></a><a class="link" href="preface.html" title="Preface">Preface</a>
</h2></div></div></div>
<a name="spirit_repository.preface.the_spirit_repository"></a><h4>
-<a name="id1128943"></a>
+<a name="id2646862"></a>
<a class="link" href="preface.html#spirit_repository.preface.the_spirit_repository">The Spirit
Repository</a>
</h4>
@@ -77,7 +77,7 @@
core library.
</p>
<a name="spirit_repository.preface.how_to_use_this_manual"></a><h4>
-<a name="id1129032"></a>
+<a name="id2649344"></a>
<a class="link" href="preface.html#spirit_repository.preface.how_to_use_this_manual">How to use
this manual</a>
</h4>
@@ -86,7 +86,7 @@
icons precede some text to indicate:
</p>
<div class="table">
-<a name="id1129045"></a><p class="title"><b>Table 1. Icons</b></p>
+<a name="id2649364"></a><p class="title"><b>Table 1. Icons</b></p>
<div class="table-contents"><table class="table" summary="Icons">
<colgroup>
<col>
@@ -207,7 +207,7 @@
Tools</a>.
</p>
<a name="spirit_repository.preface.support"></a><h4>
-<a name="id1129286"></a>
+<a name="id2645098"></a>
<a class="link" href="preface.html#spirit_repository.preface.support">Support</a>
</h4>
<p>
Modified: trunk/libs/spirit/repository/doc/html/spirit_repository/qi_components/directives/confix.html
==============================================================================
--- trunk/libs/spirit/repository/doc/html/spirit_repository/qi_components/directives/confix.html (original)
+++ trunk/libs/spirit/repository/doc/html/spirit_repository/qi_components/directives/confix.html 2009-08-13 09:00:20 EDT (Thu, 13 Aug 2009)
@@ -28,7 +28,7 @@
Qi Confix Parser Directive</a>
</h4></div></div></div>
<a name="spirit_repository.qi_components.directives.confix.description"></a><h6>
-<a name="id1133354"></a>
+<a name="id2695643"></a>
<a class="link" href="confix.html#spirit_repository.qi_components.directives.confix.description">Description</a>
</h6>
<p>
@@ -95,20 +95,20 @@
</p></td></tr>
</table></div>
<a name="spirit_repository.qi_components.directives.confix.header"></a><h6>
-<a name="id1134122"></a>
+<a name="id2696600"></a>
<a class="link" href="confix.html#spirit_repository.qi_components.directives.confix.header">Header</a>
</h6>
<pre class="programlisting"><span class="comment">// forwards to <boost/spirit/repository/home/qi/directive/confix.hpp>
</span><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">repository</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">qi_confix</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
</pre>
<a name="spirit_repository.qi_components.directives.confix.synopsis"></a><h6>
-<a name="id1134200"></a>
+<a name="id2696701"></a>
<a class="link" href="confix.html#spirit_repository.qi_components.directives.confix.synopsis">Synopsis</a>
</h6>
<pre class="programlisting"><span class="identifier">confix</span><span class="special">(</span><span class="identifier">prefix</span><span class="special">,</span> <span class="identifier">suffix</span><span class="special">)[</span><span class="identifier">subject</span><span class="special">]</span>
</pre>
<a name="spirit_repository.qi_components.directives.confix.parameters"></a><h6>
-<a name="id1134253"></a>
+<a name="id2696768"></a>
<a class="link" href="confix.html#spirit_repository.qi_components.directives.confix.parameters">Parameters</a>
</h6>
<div class="informaltable"><table class="table">
@@ -172,7 +172,7 @@
All three parameters can be arbitrarily complex parsers themselves.
</p>
<a name="spirit_repository.qi_components.directives.confix.attribute"></a><h6>
-<a name="id1134395"></a>
+<a name="id2696931"></a>
<a class="link" href="confix.html#spirit_repository.qi_components.directives.confix.attribute">Attribute</a>
</h6>
<p>
@@ -198,7 +198,7 @@
</p></td></tr>
</table></div>
<a name="spirit_repository.qi_components.directives.confix.example"></a><h6>
-<a name="id1134632"></a>
+<a name="id2697244"></a>
<a class="link" href="confix.html#spirit_repository.qi_components.directives.confix.example">Example</a>
</h6>
<p>
@@ -208,7 +208,7 @@
see confix.cpp)
</p>
<a name="spirit_repository.qi_components.directives.confix.prerequisites"></a><h6>
-<a name="id1134667"></a>
+<a name="id2697291"></a>
<a class="link" href="confix.html#spirit_repository.qi_components.directives.confix.prerequisites">Prerequisites</a>
</h6>
<p>
@@ -251,7 +251,7 @@
<p>
</p>
<a name="spirit_repository.qi_components.directives.confix.parsing_different_comment_styles"></a><h6>
-<a name="id1135085"></a>
+<a name="id2697814"></a>
<a class="link" href="confix.html#spirit_repository.qi_components.directives.confix.parsing_different_comment_styles">Parsing
Different Comment Styles</a>
</h6>
@@ -311,7 +311,7 @@
This is a comment */</span> </code>".
</p>
<a name="spirit_repository.qi_components.directives.confix.parsing_tagged_data"></a><h6>
-<a name="id1136760"></a>
+<a name="id2698523"></a>
<a class="link" href="confix.html#spirit_repository.qi_components.directives.confix.parsing_tagged_data">Parsing
Tagged Data</a>
</h6>
Modified: trunk/libs/spirit/repository/doc/html/spirit_repository/qi_components/directives/distinct.html
==============================================================================
--- trunk/libs/spirit/repository/doc/html/spirit_repository/qi_components/directives/distinct.html (original)
+++ trunk/libs/spirit/repository/doc/html/spirit_repository/qi_components/directives/distinct.html 2009-08-13 09:00:20 EDT (Thu, 13 Aug 2009)
@@ -28,7 +28,7 @@
Qi Distinct Parser Directive</a>
</h4></div></div></div>
<a name="spirit_repository.qi_components.directives.distinct.description"></a><h6>
-<a name="id1137113"></a>
+<a name="id2698962"></a>
<a class="link" href="distinct.html#spirit_repository.qi_components.directives.distinct.description">Description</a>
</h6>
<p>
@@ -144,20 +144,20 @@
above.
</p>
<a name="spirit_repository.qi_components.directives.distinct.header"></a><h6>
-<a name="id1138350"></a>
+<a name="id2700522"></a>
<a class="link" href="distinct.html#spirit_repository.qi_components.directives.distinct.header">Header</a>
</h6>
<pre class="programlisting"><span class="comment">// forwards to <boost/spirit/repository/home/qi/directive/distinct.hpp>
</span><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">repository</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">qi_distinct</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
</pre>
<a name="spirit_repository.qi_components.directives.distinct.synopsis"></a><h6>
-<a name="id1138428"></a>
+<a name="id2700625"></a>
<a class="link" href="distinct.html#spirit_repository.qi_components.directives.distinct.synopsis">Synopsis</a>
</h6>
<pre class="programlisting"><span class="identifier">distinct</span><span class="special">(</span><span class="identifier">tail</span><span class="special">)[</span><span class="identifier">subject</span><span class="special">]</span>
</pre>
<a name="spirit_repository.qi_components.directives.distinct.parameters"></a><h6>
-<a name="id1138472"></a>
+<a name="id2700681"></a>
<a class="link" href="distinct.html#spirit_repository.qi_components.directives.distinct.parameters">Parameters</a>
</h6>
<div class="informaltable"><table class="table">
@@ -210,7 +210,7 @@
All two parameters can be arbitrary complex parsers themselves.
</p>
<a name="spirit_repository.qi_components.directives.distinct.attribute"></a><h6>
-<a name="id1138576"></a>
+<a name="id2700798"></a>
<a class="link" href="distinct.html#spirit_repository.qi_components.directives.distinct.attribute">Attribute</a>
</h6>
<p>
@@ -224,7 +224,7 @@
<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--></span> <span class="identifier">distinct</span><span class="special">(</span><span class="identifier">b</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">A</span>
</pre>
<a name="spirit_repository.qi_components.directives.distinct.example"></a><h6>
-<a name="id1138694"></a>
+<a name="id2700950"></a>
<a class="link" href="distinct.html#spirit_repository.qi_components.directives.distinct.example">Example</a>
</h6>
<p>
@@ -232,7 +232,7 @@
parser. distinct.cpp)
</p>
<a name="spirit_repository.qi_components.directives.distinct.prerequisites"></a><h6>
-<a name="id1138726"></a>
+<a name="id2700994"></a>
<a class="link" href="distinct.html#spirit_repository.qi_components.directives.distinct.prerequisites">Prerequisites</a>
</h6>
<p>
@@ -269,7 +269,7 @@
<p>
</p>
<a name="spirit_repository.qi_components.directives.distinct.using_the_distinct_directive_to_match_keywords"></a><h6>
-<a name="id1138970"></a>
+<a name="id2701302"></a>
<a class="link" href="distinct.html#spirit_repository.qi_components.directives.distinct.using_the_distinct_directive_to_match_keywords">Using
The Distinct Directive to Match keywords</a>
</h6>
Modified: trunk/libs/spirit/repository/doc/html/spirit_repository/qi_components/nonterminal/subrule.html
==============================================================================
--- trunk/libs/spirit/repository/doc/html/spirit_repository/qi_components/nonterminal/subrule.html (original)
+++ trunk/libs/spirit/repository/doc/html/spirit_repository/qi_components/nonterminal/subrule.html 2009-08-13 09:00:20 EDT (Thu, 13 Aug 2009)
@@ -28,7 +28,7 @@
Qi subrules</a>
</h4></div></div></div>
<a name="spirit_repository.qi_components.nonterminal.subrule.description"></a><h6>
-<a name="id1139904"></a>
+<a name="id2702457"></a>
<a class="link" href="subrule.html#spirit_repository.qi_components.nonterminal.subrule.description">Description</a>
</h6>
<p>
@@ -39,12 +39,11 @@
</p>
<p>
The strength of subrules is performance. Replacing some rules with subrules
- can make a parser faster (for example the <span class="emphasis"><em>Spirit.Qi</em></span>
- calc1 and mini_xml2 examples, compiled with gcc-4.4, are respectively 6%
- and 8% faster when using subrules instead of rules). The reason is that
- subrules allow aggressive inlining by the C++ compiler, whereas the implementation
- of rules is based on a virtual function call which 1. has a fixed run-time
- overhead and 2. stops inlining.
+ can make a parser slightly faster (see <a class="link" href="subrule.html#spirit_repository.qi_components.nonterminal.subrule.performance">Performance</a>
+ below for measurements). The reason is that subrules allow aggressive inlining
+ by the C++ compiler, whereas the implementation of rules is based on a
+ virtual function call which, depending on the compiler, can have some run-time
+ overhead and stop inlining.
</p>
<p>
The weaknesses of subrules are:
@@ -57,9 +56,8 @@
</li>
<li class="listitem">
subrules put a massive strain on the C++ compiler. They increase compile
- times (by 20% in the mini_xml2 case described above), memory usage during
- compilation (by 14% in that case), and also the risk of hitting compiler
- limits and/or bugs.
+ times and memory usage during compilation, and also increase the risk
+ of hitting compiler limits and/or bugs.
</li>
</ul></div>
<p>
@@ -103,21 +101,21 @@
most performance-critical parts), whereas the rest can use rules and grammars.
</p>
<a name="spirit_repository.qi_components.nonterminal.subrule.header"></a><h6>
-<a name="id1140288"></a>
+<a name="id2702944"></a>
<a class="link" href="subrule.html#spirit_repository.qi_components.nonterminal.subrule.header">Header</a>
</h6>
<pre class="programlisting"><span class="comment">// forwards to <boost/spirit/repository/home/qi/nonterminal/subrule.hpp>
</span><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">repository</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">qi_subrule</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
</pre>
<a name="spirit_repository.qi_components.nonterminal.subrule.synopsis__declaration_"></a><h6>
-<a name="id1140364"></a>
+<a name="id2703046"></a>
<a class="link" href="subrule.html#spirit_repository.qi_components.nonterminal.subrule.synopsis__declaration_">Synopsis
(declaration)</a>
</h6>
<pre class="programlisting"><span class="identifier">subrule</span><span class="special"><</span><span class="identifier">ID</span><span class="special">,</span> <span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">,</span> <span class="identifier">A3</span><span class="special">></span> <span class="identifier">sr</span><span class="special">(</span><span class="identifier">name</span><span class="special">);</span>
</pre>
<a name="spirit_repository.qi_components.nonterminal.subrule.parameters__declaration_"></a><h6>
-<a name="id1140437"></a>
+<a name="id2703144"></a>
<a class="link" href="subrule.html#spirit_repository.qi_components.nonterminal.subrule.parameters__declaration_">Parameters
(declaration)</a>
</h6>
@@ -182,7 +180,7 @@
</tbody>
</table></div>
<a name="spirit_repository.qi_components.nonterminal.subrule.synopsis__usage_"></a><h6>
-<a name="id1140570"></a>
+<a name="id2703307"></a>
<a class="link" href="subrule.html#spirit_repository.qi_components.nonterminal.subrule.synopsis__usage_">Synopsis
(usage)</a>
</h6>
@@ -211,7 +209,7 @@
<span class="special">)(</span><span class="identifier">a1</span><span class="special">,</span> <span class="identifier">a2</span><span class="special">,</span> <span class="special">...)</span> <span class="comment">// Arguments to group, i.e. to start subrule srA
</span></pre>
<a name="spirit_repository.qi_components.nonterminal.subrule.parameters__usage_"></a><h6>
-<a name="id1140806"></a>
+<a name="id2703601"></a>
<a class="link" href="subrule.html#spirit_repository.qi_components.nonterminal.subrule.parameters__usage_">Parameters
(usage)</a>
</h6>
@@ -335,7 +333,7 @@
</tbody>
</table></div>
<a name="spirit_repository.qi_components.nonterminal.subrule.groups"></a><h6>
-<a name="id1142212"></a>
+<a name="id2703978"></a>
<a class="link" href="subrule.html#spirit_repository.qi_components.nonterminal.subrule.groups">Groups</a>
</h6>
<p>
@@ -380,7 +378,7 @@
</span><span class="special">;</span>
</pre>
<a name="spirit_repository.qi_components.nonterminal.subrule.attributes"></a><h6>
-<a name="id1142612"></a>
+<a name="id2704480"></a>
<a class="link" href="subrule.html#spirit_repository.qi_components.nonterminal.subrule.attributes">Attributes</a>
</h6>
<p>
@@ -408,7 +406,7 @@
</li>
</ul></div>
<a name="spirit_repository.qi_components.nonterminal.subrule.locals"></a><h6>
-<a name="id1142688"></a>
+<a name="id2704589"></a>
<a class="link" href="subrule.html#spirit_repository.qi_components.nonterminal.subrule.locals">Locals</a>
</h6>
<p>
@@ -418,7 +416,7 @@
refer to the subrule's locals, if present.
</p>
<a name="spirit_repository.qi_components.nonterminal.subrule.example"></a><h6>
-<a name="id1142724"></a>
+<a name="id2704639"></a>
<a class="link" href="subrule.html#spirit_repository.qi_components.nonterminal.subrule.example">Example</a>
</h6>
<p>
@@ -517,8 +515,236 @@
structures are not shown here. The full example above can be found here:
<a href="../../../../../example/qi/mini_xml2_sr.cpp" target="_top">../../example/qi/mini_xml2_sr.cpp</a>
</p>
+<a name="spirit_repository.qi_components.nonterminal.subrule.performance"></a><h6>
+<a name="id2706281"></a>
+ <a class="link" href="subrule.html#spirit_repository.qi_components.nonterminal.subrule.performance">Performance</a>
+ </h6>
+<p>
+ This table compares run-time and compile-time performance when converting
+ examples to subrules, with various compilers.
+ </p>
+<div class="table">
+<a name="id2706301"></a><p class="title"><b>Table 2. Subrules performance</b></p>
+<div class="table-contents"><table class="table" summary="Subrules performance">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Example
+ </p>
+ </th>
+<th>
+ <p>
+ Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ Speed (run-time)
+ </p>
+ </th>
+<th>
+ <p>
+ Time (compile-time)
+ </p>
+ </th>
+<th>
+ <p>
+ Memory (compile-time)
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ calc1_sr
+ </p>
+ </td>
+<td>
+ <p>
+ gcc 4.4.1
+ </p>
+ </td>
+<td>
+ <p>
+ +6%
+ </p>
+ </td>
+<td>
+ <p>
+ n/a
+ </p>
+ </td>
+<td>
+ <p>
+ n/a
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ calc1_sr
+ </p>
+ </td>
+<td>
+ <p>
+ Visual C++ 2008 (VC9)
+ </p>
+ </td>
+<td>
+ <p>
+ +5%
+ </p>
+ </td>
+<td>
+ <p>
+ n/a
+ </p>
+ </td>
+<td>
+ <p>
+ n/a
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mini_xml2_sr
+ </p>
+ </td>
+<td>
+ <p>
+ gcc 3.4.6
+ </p>
+ </td>
+<td>
+ <p>
+ -1%
+ </p>
+ </td>
+<td>
+ <p>
+ +54%
+ </p>
+ </td>
+<td>
+ <p>
+ +32%
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mini_xml2_sr
+ </p>
+ </td>
+<td>
+ <p>
+ gcc 4.1.2
+ </p>
+ </td>
+<td>
+ <p>
+ +5%
+ </p>
+ </td>
+<td>
+ <p>
+ +58%
+ </p>
+ </td>
+<td>
+ <p>
+ +25%
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mini_xml2_sr
+ </p>
+ </td>
+<td>
+ <p>
+ gcc 4.4.1
+ </p>
+ </td>
+<td>
+ <p>
+ +8%
+ </p>
+ </td>
+<td>
+ <p>
+ +20%
+ </p>
+ </td>
+<td>
+ <p>
+ +14%
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mini_xml2_sr
+ </p>
+ </td>
+<td>
+ <p>
+ Visual C++ 2008 (VC9)
+ </p>
+ </td>
+<td>
+ <p>
+ +9%
+ </p>
+ </td>
+<td>
+ <p>
+ +52%
+ </p>
+ </td>
+<td>
+ <p>
+ +40%
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><p>
+ The columns are:
+ </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+<span class="bold"><strong>Speed (run-time)</strong></span>: speed-up of the parser
+ resulting from the use of subrules (higher is better).
+ </li>
+<li class="listitem">
+<span class="bold"><strong>Time (compile-time)</strong></span>: increase in compile
+ time (lower is better).
+ </li>
+<li class="listitem">
+<span class="bold"><strong>Memory (compile-time)</strong></span>: increase in compiler
+ memory usage (lower is better).
+ </li>
+</ul></div>
<a name="spirit_repository.qi_components.nonterminal.subrule.notes"></a><h6>
-<a name="id1144068"></a>
+<a name="id2706612"></a>
<a class="link" href="subrule.html#spirit_repository.qi_components.nonterminal.subrule.notes">Notes</a>
</h6>
<p>
Modified: trunk/libs/spirit/repository/doc/html/spirit_repository/qi_components/primitive/flush_multi_pass.html
==============================================================================
--- trunk/libs/spirit/repository/doc/html/spirit_repository/qi_components/primitive/flush_multi_pass.html (original)
+++ trunk/libs/spirit/repository/doc/html/spirit_repository/qi_components/primitive/flush_multi_pass.html 2009-08-13 09:00:20 EDT (Thu, 13 Aug 2009)
@@ -28,7 +28,7 @@
Qi flush_multi_pass parser</a>
</h4></div></div></div>
<a name="spirit_repository.qi_components.primitive.flush_multi_pass.description"></a><h6>
-<a name="id1129363"></a>
+<a name="id2645212"></a>
<a class="link" href="flush_multi_pass.html#spirit_repository.qi_components.primitive.flush_multi_pass.description">Description</a>
</h6>
<p>
@@ -53,20 +53,20 @@
<code class="computeroutput"><span class="identifier">eps</span></code>).
</p>
<a name="spirit_repository.qi_components.primitive.flush_multi_pass.header"></a><h6>
-<a name="id1129471"></a>
+<a name="id2645382"></a>
<a class="link" href="flush_multi_pass.html#spirit_repository.qi_components.primitive.flush_multi_pass.header">Header</a>
</h6>
<pre class="programlisting"><span class="comment">// forwards to <boost/spirit/repository/home/qi/primitive/flush_multi_pass.hpp>
</span><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">repository</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">qi_flush_multi_pass</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
</pre>
<a name="spirit_repository.qi_components.primitive.flush_multi_pass.synopsis"></a><h6>
-<a name="id1129544"></a>
+<a name="id2694289"></a>
<a class="link" href="flush_multi_pass.html#spirit_repository.qi_components.primitive.flush_multi_pass.synopsis">Synopsis</a>
</h6>
<pre class="programlisting"><span class="identifier">flush_multi_pass</span>
</pre>
<a name="spirit_repository.qi_components.primitive.flush_multi_pass.parameters"></a><h6>
-<a name="id1129566"></a>
+<a name="id2694324"></a>
<a class="link" href="flush_multi_pass.html#spirit_repository.qi_components.primitive.flush_multi_pass.parameters">Parameters</a>
</h6>
<p>
@@ -74,7 +74,7 @@
not require any parameters.
</p>
<a name="spirit_repository.qi_components.primitive.flush_multi_pass.attribute"></a><h6>
-<a name="id1129590"></a>
+<a name="id2694362"></a>
<a class="link" href="flush_multi_pass.html#spirit_repository.qi_components.primitive.flush_multi_pass.attribute">Attribute</a>
</h6>
<p>
@@ -84,7 +84,7 @@
<pre class="programlisting"><span class="identifier">flush_multi_pass</span> <span class="special">--></span> <span class="identifier">unused</span>
</pre>
<a name="spirit_repository.qi_components.primitive.flush_multi_pass.example"></a><h6>
-<a name="id1129639"></a>
+<a name="id2694434"></a>
<a class="link" href="flush_multi_pass.html#spirit_repository.qi_components.primitive.flush_multi_pass.example">Example</a>
</h6>
<p>
@@ -96,7 +96,7 @@
a function prototype (for the full example code see here: flush_multi_pass.cpp)
</p>
<a name="spirit_repository.qi_components.primitive.flush_multi_pass.prerequisites"></a><h6>
-<a name="id1129672"></a>
+<a name="id2694483"></a>
<a class="link" href="flush_multi_pass.html#spirit_repository.qi_components.primitive.flush_multi_pass.prerequisites">Prerequisites</a>
</h6>
<p>
@@ -133,7 +133,7 @@
<p>
</p>
<a name="spirit_repository.qi_components.primitive.flush_multi_pass.clearing_the_internal_buffer"></a><h6>
-<a name="id1129888"></a>
+<a name="id2694760"></a>
<a class="link" href="flush_multi_pass.html#spirit_repository.qi_components.primitive.flush_multi_pass.clearing_the_internal_buffer">Clearing
the internal buffer</a>
</h6>
Modified: trunk/libs/spirit/repository/doc/qi/subrule.qbk
==============================================================================
--- trunk/libs/spirit/repository/doc/qi/subrule.qbk (original)
+++ trunk/libs/spirit/repository/doc/qi/subrule.qbk 2009-08-13 09:00:20 EDT (Thu, 13 Aug 2009)
@@ -16,21 +16,20 @@
static version of the rule.
The strength of subrules is performance. Replacing some rules with subrules
-can make a parser faster (for example the __qi__ calc1 and mini_xml2
-examples, compiled with gcc-4.4, are respectively 6% and 8% faster when using
-subrules instead of rules). The reason is that subrules allow aggressive
-inlining by the C++ compiler, whereas the implementation of rules is based on
-a virtual function call which 1. has a fixed run-time overhead and 2. stops
-inlining.
+can make a parser slightly faster (see
+[link spirit_repository.qi_components.nonterminal.subrule.performance Performance]
+below for measurements). The reason is that subrules allow aggressive inlining
+by the C++ compiler, whereas the implementation of rules is based on a virtual
+function call which, depending on the compiler, can have some run-time overhead
+and stop inlining.
The weaknesses of subrules are:
* subrules can only be defined and used within the same parser expression. A
subrule cannot be defined at one location, and then used in another location.
* subrules put a massive strain on the C++ compiler. They increase compile
- times (by 20% in the mini_xml2 case described above), memory usage during
- compilation (by 14% in that case), and also the risk of hitting compiler
- limits and/or bugs.
+ times and memory usage during compilation, and also increase the risk of
+ hitting compiler limits and/or bugs.
[import ../../example/qi/calc1_sr.cpp]
@@ -195,6 +194,32 @@
are not shown here. The full example above can be found here:
[@../../example/qi/mini_xml2_sr.cpp]
+[heading Performance]
+
+This table compares run-time and compile-time performance when converting
+examples to subrules, with various compilers.
+
+[table Subrules performance
+
+[[Example] [Compiler]
+ [Speed (run-time)] [Time (compile-time)] [Memory (compile-time)]]
+
+[[calc1_sr] [gcc 4.4.1] [ +6%] [ n/a] [ n/a]]
+[[calc1_sr] [Visual C++ 2008 (VC9)] [ +5%] [ n/a] [ n/a]]
+[[mini_xml2_sr] [gcc 3.4.6] [ -1%] [+54%] [+32%]]
+[[mini_xml2_sr] [gcc 4.1.2] [ +5%] [+58%] [+25%]]
+[[mini_xml2_sr] [gcc 4.4.1] [ +8%] [+20%] [+14%]]
+[[mini_xml2_sr] [Visual C++ 2008 (VC9)] [ +9%] [+52%] [+40%]]
+
+]
+
+The columns are:
+
+* *Speed (run-time)*: speed-up of the parser resulting from the use of
+ subrules (higher is better).
+* *Time (compile-time)*: increase in compile time (lower is better).
+* *Memory (compile-time)*: increase in compiler memory usage (lower is better).
+
[heading Notes]
FIXME add compiler-specific bit (MSVC pragmas, g++ option)