Author: wyoung
Date: Tue May 18 21:23:20 2010
New Revision: 2652
URL: http://svn.gna.org/viewcvs/mysqlpp?rev=2652&view=rev
Log:
Reworked the "max fields" discussion in the userman to incorporate the
finding that compile time goes up almost in step with generate file
size, and to better discuss the other bad side effects of generating
files that support more fields than you require.
Modified:
trunk/doc/userman/configuration.dbx
Modified: trunk/doc/userman/configuration.dbx
URL:
http://svn.gna.org/viewcvs/mysqlpp/trunk/doc/userman/configuration.dbx?rev=2652&r1=2651&r2=2652&view=diff
==============================================================================
--- trunk/doc/userman/configuration.dbx (original)
+++ trunk/doc/userman/configuration.dbx Tue May 18 21:23:20 2010
@@ -53,58 +53,71 @@
<para>MySQL++ offers two ways to automatically build SQL
queries at run time: <xref linkend="tquery"/> and <link
linkend="ssqls">SSQLS</link>. There’s a limit on the number
- of fields these mechanisms support, primarily to avoid exceeding
- limits in some compilers. The default for each is 25 fields in the
- source distribution.<footnote><para>If you’re using a binary
- MySQL++ package, its maintainer may have increased these field
- counts so the resulting headers more closely approach the size
- limit of the compiler the package was built with. In that case,
- you can look at the top of each generated header file to find
- out how many fields each supports.</para></footnote> This is high
- enough to work with most good database designs.<footnote><para>If
- your database design has a table with more than 25 columns,
- you might consider refactoring it. It’s a fair indicator
- the design commits some sin a DBA would castigate as improper
- normalization.</para></footnote></para>
-
- <para>Perhaps your database design does need more than 25
- SSQLS fields or template query parameters. You can raise these
- limits by re-generating the <filename>lib/ssqls.h</filename>
- and/or <filename>lib/querydef.h</filename> headers. These
- files are generated by Perl scripts of the same name,
- except with a <filename>pl</filename> extension.</para>
+ of fields these mechanisms support, defaulting to 25 fields in the
+ official MySQL++ packages.<footnote><para>If you’re using
+ a third-party MySQL++ package, its maintainer may have increased
+ these field counts so the resulting headers more closely approach
+ the size limit of the compiler the package was built with. In that
+ case, you can look at the top of each generated header file to
+ find out how many fields each supports.</para></footnote> The files
+ embodying these limits are <filename>lib/querydef.h</filename> and
+ <filename>lib/ssqls.h</filename>, each generated by Perl scripts of
+ the same name but with a <filename>.pl</filename> extension.</para>
<para>The default <filename>querydef.h</filename> is small and
- its size only increases linearly with respect to field count. Even
- with an insanely large table, it shouldn’t be a problem to
- increase this file’s field limit.</para>
-
- <para>The reason we worry about large field counts exceeding
- compiler limits is all down to <filename>ssqls.h</filename>. It
- is already a rather large file with the default of 25
- fields, at over 1 MB. Worse, its size goes up
- <emphasis>quadratically</emphasis> as a function of
- field count. Doubling the default nearly quadruples
- the file size!<footnote><para>The amateur mathematician
- reading this may be wondering, why doesn’t doubling
- the field count exactly quadruple the file size, if
- it’s a quadratic relationship? It’s because
- the equation relating them has a few lower-order terms:
- <phrase role="math">N<subscript>lines</subscript> =
+ its size only increases linearly with respect to maximum field
+ count.</para>
+
+ <para><filename>ssqls.h</filename> is a totally
+ different story. The default 25 field limit
+ makes <filename>ssqls.pl</filename> generate an
+ <filename>ssqls.h</filename> over 1 MB. Worse,
+ the field limit to file size relation is
+ <emphasis>quadratic</emphasis>.<footnote><para>The file
+ size equation, for you amateur mathematicians out there,
+ is <phrase role="math">N<subscript>lines</subscript> =
18.5f<superscript>2</superscript> + 454.5f + 196.4</phrase>,
where <varname>f</varname> is the field count.</para></footnote>
- Thus the need for a field limit: many compilers have limits on the
- size of preprocessor macros. It may be that the compiler you use
- is able to cope with much larger macros than we like to generate
- by default.</para>
-
- <para>If you’re building MySQL++ from source on
- a platform that uses Autoconf, the easiest way to change
- these limits is at configuration time:</para>
-
+ This has a number of bad effects:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Generating header files to support more fields than
+ you actually require is a waste of space and bandwidth.</para>
+ </listitem>
+
+ <listitem>
+ <para>Some compilers have arbitrary limits on the size of
+ macros they’re able to parse. Exceeding these limits
+ usually causes the compiler to misbehave badly, rather than
+ fail gracefully.</para>
+ </listitem>
+
+ <listitem>
+ <para>Because it increases the size of two key files used
+ in building MySQL++ itself and programs built on it, it
+ increases compile times significantly. One test I did here
+ showed a tripling of compile time from quadrupling the field
+ limit.</para>
+ </listitem>
+
+ <listitem>
+ <para>More than 25 fields in a table is a good sign of a bad
+ database design, most likely a denormalization problem.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The default limits try to mitigate against all of these
+ factors while still being high enough to be useful with most
+ DB designs.</para>
+
+ <para>If you’re building MySQL++ from source on a platform
+ that uses Autoconf, the easiest way to change these limits is at
+ configuration time:</para>
+
<screen>
./configure --with-field-limit=50</screen>
-
+
<para>That causes the configuration script to pass the
<command>-f</command> flag to the two Perl scripts named above,
overriding the default of 25 fields. Obviously you need a
_______________________________________________
Mysqlpp-commits mailing list
[email protected]
https://mail.gna.org/listinfo/mysqlpp-commits
