Author: paul
Date: 2008-09-04 21:33:48 +0200 (Thu, 04 Sep 2008)
New Revision: 11666
Log:
r33632@frost: paul | 2008-09-04 14:30:57 -0500
Debug Sync facility information for refman and mysqltest manual:
* --enable-debug-sync configure option
* debug_sync system variable
* --debug-sync-timeout mysqld option
* --debug-sync-timeout mysql-test-run.pl option
* Thread synchronization section in test manual
(WL#4259)
Modified:
trunk/dynamic-docs/build-configure/mysqld.xml
trunk/dynamic-docs/changelog/mysqld-1.xml
trunk/dynamic-docs/command-optvars/mysqld.xml
trunk/mysqltest/programs.xml
trunk/mysqltest/writing-tests.xml
trunk/refman-6.0/dba-core.xml
trunk/refman-6.0/installing-core.xml
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:35828
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:33630
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:32972
+ 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:35828
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:33632
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:32972
Modified: trunk/dynamic-docs/build-configure/mysqld.xml
===================================================================
--- trunk/dynamic-docs/build-configure/mysqld.xml 2008-09-04 16:28:43 UTC (rev 11665)
+++ trunk/dynamic-docs/build-configure/mysqld.xml 2008-09-04 19:33:48 UTC (rev 11666)
Changed blocks: 1, Lines Added: 14, Lines Deleted: 0; 635 bytes
@@ -2078,4 +2078,18 @@
</buildoption>
+ <buildoption id="enable-debug-sync">
+
+ <formatbase format="--enable-debug-sync">
+
+ <description>Compile in Debug Sync facility</description>
+
+ </formatbase>
+ <versions>
+ <manual version="6.0"/>
+ <introduced version="6.0.6"/>
+ </versions>
+
+ </buildoption>
+
</buildoptions>
Modified: trunk/dynamic-docs/changelog/mysqld-1.xml
===================================================================
--- trunk/dynamic-docs/changelog/mysqld-1.xml 2008-09-04 16:28:43 UTC (rev 11665)
+++ trunk/dynamic-docs/changelog/mysqld-1.xml 2008-09-04 19:33:48 UTC (rev 11666)
Changed blocks: 1, Lines Added: 32, Lines Deleted: 0; 1282 bytes
@@ -25986,4 +25986,36 @@
</logentry>
+ <logentry entrytype="feature">
+
+ <tags>
+ <manual type="Debug Sync"/>
+ <manual type="--enable-debug-sync"/>
+ <manual type="--debug-sync-timeout"/>
+ <manual type="debug_sync"/>
+ <manual type="mysql-test-run.pl"/>
+ </tags>
+
+ <versions>
+ <version ver="6.0.6"/>
+ </versions>
+
+ <message>
+
+ <para>
+ The server now supports a Debug Sync facility for thread
+ synchronization during testing and debugging. To compile in this
+ facility, configure MySQL with the
+ <option>--enable-debug-sync</option> option. The
+ <literal>debug_sync</literal> system variable provides the user
+ interface Debug Sync. <command>mysqld</command> and
+ <command>mysql-test-run.pl</command> support a
+ <option>--debug-sync-timeout</option> option to enable the
+ facility and set the default synchronization point timeout.
+ </para>
+
+ </message>
+
+ </logentry>
+
</changelog>
Modified: trunk/dynamic-docs/command-optvars/mysqld.xml
===================================================================
--- trunk/dynamic-docs/command-optvars/mysqld.xml 2008-09-04 16:28:43 UTC (rev 11665)
+++ trunk/dynamic-docs/command-optvars/mysqld.xml 2008-09-04 19:33:48 UTC (rev 11666)
Changed blocks: 1, Lines Added: 65, Lines Deleted: 18; 3606 bytes
@@ -6627,60 +6627,107 @@
</mysqloption>
- <mysqloption section="server" id="default-character-set">
+ <mysqloption section="server" id="character_set">
- <xrefto id="option_mysqld_default-character-set"/>
+ <xrefto id="option_mysqld_character_set"/>
- <name>default-character-set</name>
+ <name>character-set</name>
<shortdescription lang="en">
- Set the default character set
+ The default character set
</shortdescription>
<seealso xref="character-set-server"/>
- <deprecated version="5.0"/>
+ <deprecated version="4.1.1"/>
<types>
- <optype class="cmdline" format="--default-character-set=name" />
- <optype class="cmdline" format="-C" setvar="default-character-set"/>
- <optype class="mycnf" format="default-character-set"/>
+ <optype class="cmdline" format="--character_set=name" setvar="character_set"
+ outversion="4.1.1"/>
+ <vartype isdynamic="no" class="system" outversion="4.1.1"/>
</types>
<values vartype="string" platform="all"/>
<versions>
<manual version="4.1"/>
- <introduced version="4.1.3"/>
- <manual version="5.0"/>
</versions>
</mysqloption>
- <mysqloption section="server" id="character_set">
+ <mysqloption section="server" id="debug_sync">
- <xrefto id="option_mysqld_character_set"/>
+ <xrefto id="option_mysqld_debug_sunc"/>
- <name>character-set</name>
+ <name>debug_sync</name>
<shortdescription lang="en">
- The default character set
+ Interface to Debug Sync facility
</shortdescription>
+ <types>
+ <vartype isdynamic="yes" class="system" scope="both"/>
+ </types>
+
+ <values vartype="string" platform="all"/>
+
+ <versions>
+ <manual version="6.0"/>
+ <introduced version="6.0.6"/>
+ </versions>
+
+ </mysqloption>
+
+ <mysqloption section="server" id="debug-sync-timeout">
+
+ <xrefto id="option_mysqld_debug-sync-timeout"/>
+
+ <name>debug-sync-timeout</name>
+
+ <shortdescription lang="en">
+ Timeout for Debug Sync synchronization points
+ </shortdescription>
+
+ <types>
+ <optype class="cmdline" format="--debug-sync-timeout=#" />
+ <optype class="mycnf"/>
+ </types>
+
+ <values vartype="numeric" platform="all"/>
+
+ <versions>
+ <manual version="6.0"/>
+ <introduced version="6.0.6"/>
+ </versions>
+
+ </mysqloption>
+
+ <mysqloption section="server" id="default-character-set">
+
+ <xrefto id="option_mysqld_default-character-set"/>
+
+ <name>default-character-set</name>
+
+ <shortdescription lang="en">
+ Set the default character set
+ </shortdescription>
+
<seealso xref="character-set-server"/>
- <deprecated version="4.1.1"/>
+ <deprecated version="5.0"/>
<types>
- <optype class="cmdline" format="--character_set=name" setvar="character_set"
- outversion="4.1.1"/>
- <vartype isdynamic="no" class="system" outversion="4.1.1"/>
+ <optype class="cmdline" format="--default-character-set=name" />
+ <optype class="cmdline" format="-C" setvar="default-character-set"/>
+ <optype class="mycnf" format="default-character-set"/>
</types>
<values vartype="string" platform="all"/>
<versions>
<manual version="4.1"/>
+ <introduced version="4.1.3"/>
+ <manual version="5.0"/>
</versions>
</mysqloption>
Modified: trunk/mysqltest/programs.xml
===================================================================
--- trunk/mysqltest/programs.xml 2008-09-04 16:28:43 UTC (rev 11665)
+++ trunk/mysqltest/programs.xml 2008-09-04 19:33:48 UTC (rev 11666)
Changed blocks: 1, Lines Added: 42, Lines Deleted: 0; 1941 bytes
@@ -2066,6 +2066,48 @@
<para>
<indexterm>
<primary>mysql-test-run.pl</primary>
+ <secondary>debug-sync-timeout option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>debug-sync-timeout option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--debug-sync-timeout=<replaceable>N</replaceable></option>
+ </para>
+
+ <para>
+ Controls whether the Debug Sync facility for testing and
+ debugging is enabled. The option value is a timeout in
+ seconds. The default value is 300. A value of 0 disables
+ Debug Sync. The value of this option also becomes the
+ default timeout for individual synchronization points.
+ </para>
+
+ <para>
+ <command>mysql-test-run.pl</command> passes
+ <option>--loose-debug-sync-timeout=<replaceable>N</replaceable></option>
+ to <command>mysqld</command>. The <option>--loose</option>
+ prefix is used so that <command>mysqld</command> does not
+ fail if Debug Sync is not compiled in.
+ </para>
+
+ <para>
+ For information about using the Debug Sync facility for
+ testing, see
+ <xref linkend="writing-tests-thread-synchronization"/>.
+ </para>
+
+ <para>
+ This option was added in MySQL 6.0.6.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
<secondary>do-test option</secondary>
</indexterm>
Modified: trunk/mysqltest/writing-tests.xml
===================================================================
--- trunk/mysqltest/writing-tests.xml 2008-09-04 16:28:43 UTC (rev 11665)
+++ trunk/mysqltest/writing-tests.xml 2008-09-04 19:33:48 UTC (rev 11666)
Changed blocks: 5, Lines Added: 62, Lines Deleted: 12; 4126 bytes
@@ -1533,10 +1533,8 @@
</programlisting>
<para>
-Some tests require
- of a particular binary log format.
- You can exercise control over the binary log format in
- two ways:
+ Some tests require of a particular binary log format. You can
+ exercise control over the binary log format in two ways:
</para>
<itemizedlist>
@@ -1650,8 +1648,8 @@
in the <filename>combinations</filename> file should include the
leading dashes. (Options in <filename>my.cnf</filename> files
are given without the leading dashes.)
-<command>mysql-test-run.pl</command> displays the section name following
-the test name when it reports the test result.
+ <command>mysql-test-run.pl</command> displays the section name
+ following the test name when it reports the test result.
</para>
<para>
@@ -1693,8 +1691,8 @@
</programlisting>
<para>
- The following files can be used for tests that support two binary log
- formats:
+ The following files can be used for tests that support two
+ binary log formats:
</para>
<programlisting>
@@ -1943,6 +1941,58 @@
</section>
+ <section id="writing-tests-thread-synchronization">
+
+ <title>Thread Synchronization in Test Cases</title>
+
+ <indexterm>
+ <primary>thread synchronization</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>Debug Sync facility</primary>
+ </indexterm>
+
+ <para>
+ The Debug Sync facility allows placement synchronization points in
+ the code. They can be activated by statements that set the
+ <literal>debug_sync</literal> system variable. An active
+ synchronization point can emit a signal and/or wait for a signal
+ to be emitted by another thread. This waiting times out after 300
+ seconds by default. The
+ <option>--debug-sync-timeout=<replaceable>N</replaceable></option>
+ option for <command>mysql-test-run.pl</command> changes that
+ timeout to <replaceable>N</replaceable> seconds. A timeout of zero
+ disables the facility altogether, so that synchronization points
+ will not emit or wait for signals, even if activated.
+ </para>
+
+ <para>
+ The purpose of the timeout is to avoid a complete lockup in test
+ cases. If for some reason the expected signal is not emitted by
+ any thread, the execution of the affected statement will not block
+ forever. A warning shows up when the timeout happens. That makes a
+ difference in the test result so that it will not go undetected.
+ </para>
+
+ <para>
+ For test cases that require the Debug Sync facility, include the
+ following line in the test case file:
+ </para>
+
+<programlisting>
+--source include/have_debug_sync.inc
+</programlisting>
+
+ <para>
+ For a description of the Debug Sync facility and how to use
+ synchronization points, see
+ <ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Test_Synchronization">MySQL
+ Internals: Test Synchronization</ulink>.
+ </para>
+
+ </section>
+
<section id="writing-tests-other-tips">
<title>Other Tips for Writing Test Cases</title>
@@ -2033,10 +2083,10 @@
for filesystem operations. This used to be very common, but OS
commands tend to be platform specific, which reduces test
portability. <command>mysqltest</command> now has several
- commands to perform these operations portably, so these commands should
- be used instead: <literal>remove_file</literal>,
- <literal>chmod_file</literal>, <literal>mkdir</literal>, and
- so forth.
+ commands to perform these operations portably, so these
+ commands should be used instead:
+ <literal>remove_file</literal>, <literal>chmod_file</literal>,
+ <literal>mkdir</literal>, and so forth.
</para>
</listitem>
Modified: trunk/refman-6.0/dba-core.xml
===================================================================
--- trunk/refman-6.0/dba-core.xml 2008-09-04 16:28:43 UTC (rev 11665)
+++ trunk/refman-6.0/dba-core.xml 2008-09-04 19:33:48 UTC (rev 11666)
Changed blocks: 2, Lines Added: 88, Lines Deleted: 0; 4187 bytes
@@ -837,6 +837,46 @@
</listitem>
<listitem>
+ <para id="option_mysqld_debug-sync-timeout">
+ <indexterm>
+ <primary>mysqld</primary>
+ <secondary>debug-sync-timeout option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>debug-sync-timeout option</primary>
+ <secondary>mysqld</secondary>
+ </indexterm>
+
+ <option>--debug-sync-timeout=<replaceable>N</replaceable></option>
+ </para>
+
+ <para condition="dynamic:optvar:item" role="6.0:mysqld:debug-sync-timeout"/>
+
+ <para>
+ Controls whether the Debug Sync facility for testing and
+ debugging is enabled. Use of Debug Sync requires that MySQL
+ be configured with the <option>---enable-debug-sync</option>
+ option (see <xref linkend="configure-options"/>). The option
+ value is a timeout in seconds. The default value is 0, which
+ disables Debug Sync. To enable it, specify a value greater
+ than 0; this value also becomes the default timeout for
+ individual synchronization points.
+ </para>
+
+ <para>
+ For a description of the Debug Sync facility and how to use
+ synchronization points, see
+ <ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Test_Synchronization">MySQL
+ Internals: Test Synchronization</ulink>.
+ </para>
+
+ <para>
+ This option was added in MySQL 6.0.6.
+ </para>
+ </listitem>
+
+ <listitem>
<para id="option_mysqld_default-character-set">
<indexterm>
<primary>mysqld</primary>
@@ -4350,6 +4390,54 @@
</listitem>
<listitem>
+ <para id="option_mysqld_debug_sync">
+ <indexterm>
+ <primary>debug_sync system variable</primary>
+ </indexterm>
+
+ <literal>debug_sync</literal>
+ </para>
+
+ <para condition="dynamic:optvar:item" role="6.0:mysqld:debug_sync"/>
+
+ <para>
+ This variable is the user interface to the Debug Sync
+ facility. The global value is read only and indicates
+ whether the facility is enabled. Use of Debug Sync requires
+ that MySQL be configured with the
+ <option>---enable-debug-sync</option> option (see
+ <xref linkend="configure-options"/>). By default, Debug Sync
+ is disabled and the value of <literal>debug_sync</literal>
+ is <literal>OFF</literal>. If the server is started with
+ <option>--debug-sync-timeout=<replaceable>N</replaceable></option>,
+ where <replaceable>N</replaceable> is a timeout value
+ greater than 0, Debug Sync is enabled and the value of
+ <literal>debug_sync</literal> is <literal>ON - current
+ signal ''</literal>. Also, <replaceable>N</replaceable>
+ becomes the default timeout for individual synchronization
+ points.
+ </para>
+
+ <para>
+ The session value can be read by any user and will have the
+ same value as the global variable. The session value can be
+ set by users that have the <literal>SUPER</literal>
+ privilege to control synchronization points.
+ </para>
+
+ <para>
+ For a description of the Debug Sync facility and how to use
+ synchronization points, see
+ <ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Test_Synchronization">MySQL
+ Internals: Test Synchronization</ulink>.
+ </para>
+
+ <para>
+ This variable was added in MySQL 6.0.6.
+ </para>
+ </listitem>
+
+ <listitem>
<para id="option_mysqld_default_week_format">
<literal>default_week_format</literal>
</para>
Modified: trunk/refman-6.0/installing-core.xml
===================================================================
--- trunk/refman-6.0/installing-core.xml 2008-09-04 16:28:43 UTC (rev 11665)
+++ trunk/refman-6.0/installing-core.xml 2008-09-04 19:33:48 UTC (rev 11666)
Changed blocks: 1, Lines Added: 44, Lines Deleted: 0; 2290 bytes
@@ -8279,6 +8279,50 @@
<para>
<indexterm>
<primary>configure</primary>
+ <secondary>enable-debug-sync option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>enable-debug-sync option</primary>
+ <secondary>configure</secondary>
+ </indexterm>
+
+ To cause the Debug Sync facility to be compiled into the
+ server, use the <option>--enable-debug-sync</option> option.
+ This facility is used for testing and debugging. When
+ compiled in, Debug Sync is disabled by default. To enable
+ it, start mysqld with the
+ <option>--debug-sync-timeout=<replaceable>N</replaceable></option>
+ option, where <replaceable>N</replaceable> is a timeout
+ value greater than 0. (The default value is 0, which
+ disables Debug Sync.) <replaceable>N</replaceable> becomes
+ the default timeout for individual synchronization points.
+ </para>
+
+ <para>
+ Debug Sync is also compiled in if you configure with the
+ <option>--with-debug</option> option (which implies
+ <option>--enable-debug-sync</option>), unless you also use
+ the <option>--disable-debug-sync</option> option.
+ </para>
+
+ <para>
+ For a description of the Debug Sync facility and how to use
+ synchronization points, see [XREF Internals manual].
+ <ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Test_Synchronization">MySQL
+ Internals: Test Synchronization</ulink>.
+ </para>
+
+ <para>
+ The --enable-debug-sync and --disable-debug-sync options
+ were added in MySQL 6.0.6.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>configure</primary>
<secondary>enable-thread-safe-client option</secondary>
</indexterm>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r11666 - in trunk: . dynamic-docs/build-configure dynamic-docs/changelog dynamic-docs/command-optvars mysqltest refman-... | paul.dubois | 4 Sep |
