Author: paul
Date: 2008-10-03 18:54:16 +0200 (Fri, 03 Oct 2008)
New Revision: 11975
Log:
r34461@frost: paul | 2008-10-03 11:52:09 -0500
Additional information about what happens when reconnect occurs
Additional information about mysql_ping() and reconnect
Modified:
trunk/refman-4.1/apis-c.xml
trunk/refman-5.0/apis-c.xml
trunk/refman-5.1/apis-c.xml
trunk/refman-6.0/apis-c.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:34455
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:33554
+ 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:35828
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:34461
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:33554
Modified: trunk/refman-4.1/apis-c.xml
===================================================================
--- trunk/refman-4.1/apis-c.xml 2008-10-03 15:50:44 UTC (rev 11974)
+++ trunk/refman-4.1/apis-c.xml 2008-10-03 16:54:16 UTC (rev 11975)
Changed blocks: 4, Lines Added: 62, Lines Deleted: 11; 4679 bytes
@@ -5679,17 +5679,40 @@
<para>
Checks whether the connection to the server is working. If the
- connection has gone down, an attempt to reconnect is made unless
- auto-reconnect is disabled.
+ connection has gone down and auto-reconnect is enabled an
+ attempt to reconnect is made. If the connection is down and
+ auto-reconnect is disabled,
+ <function role="capi">mysql_ping()</function> returns an error.
</para>
<para>
- This function can be used by clients that remain idle for a long
- while, to check whether the server has closed the connection and
- reconnect if necessary.
+ Auto-reconnect is enabled by default.
</para>
<para>
+ <function role="capi">mysql_ping()</function> can be used by
+ clients that remain idle for a long while, to check whether the
+ server has closed the connection and reconnect if necessary.
+ </para>
+
+ <para>
+ If <function role="capi">mysql_ping()</function>) does cause a
+ reconnect, there is no explicit indication of it. To determine
+ whether a reconnect occurs, call
+ <function role="capi">mysql_thread_id()</function> to get the
+ original connection identifier before calling
+ <function role="capi">mysql_ping()</function>, and then call
+ <function role="capi">mysql_thread_id()</function> again to see
+ whether the identifier has changed.
+ </para>
+
+ <para>
+ If reconnect occurs, some characteristics of the connection will
+ have been reset. For details about these characteristics, see
+ <xref linkend="auto-reconnect"/>.
+ </para>
+
+ <para>
<emphasis role="bold">Return Values</emphasis>
</para>
@@ -13330,17 +13353,25 @@
<section id="auto-reconnect">
- <title>Controlling Automatic Reconnect Behavior</title>
+ <title>Controlling Automatic Reconnection Behavior</title>
<para>
- The MySQL client library can perform an automatic reconnect to the
- server if it finds that the connection is down when you attempt to
- send a statement to the server to be executed. In this case, the
- library tries once to reconnect to the server and send the
- statement again.
+ The MySQL client library can perform an automatic reconnection to
+ the server if it finds that the connection is down when you
+ attempt to send a statement to the server to be executed. In this
+ case, the library tries once to reconnect to the server and send
+ the statement again.
</para>
<para>
+ If the connection has gone down, the
+ <function role="capi">mysql_ping()</function> function performs a
+ reconnect if auto-reconnect is enabled. If auto-reconnect is
+ disabled, <function role="capi">mysql_ping()</function> returns an
+ error instead.
+ </para>
+
+ <para>
Some client programs might provide the capability of controlling
automatic reconnection. For example, <command>mysql</command>
reconnects by default, but the <option>--skip-reconnect</option>
@@ -13348,6 +13379,17 @@
</para>
<para>
+ If an automatic reconnection does occur (for example, as a result
+ of calling <function role="capi">mysql_ping()</function>), there
+ is no explicit indication of it. To check for reconnection, call
+ <function role="capi">mysql_thread_id()</function> to get the
+ original connection identifier before calling
+ <function role="capi">mysql_ping()</function>, and then call
+ <function role="capi">mysql_thread_id()</function> again to see
+ whether the identifier has changed.
+ </para>
+
+ <para>
Automatic reconnection can be convenient because you need not
implement your own reconnect code, but if a reconnection does
occur, several aspects of the connection state are reset and your
@@ -13420,6 +13462,15 @@
</itemizedlist>
+ <para>
+ If the connection drops, it is possible that the session
+ associated with the connection on the server side will still be
+ running if the server has not yet detected that the client is no
+ longer connected. In this case, any locks held by the original
+ connection still belong to that session, so you may want to kill
+ it by calling <function role="capi">mysql_kill()</function>.
+ </para>
+
</section>
<section id="c-api-problems">
Modified: trunk/refman-5.0/apis-c.xml
===================================================================
--- trunk/refman-5.0/apis-c.xml 2008-10-03 15:50:44 UTC (rev 11974)
+++ trunk/refman-5.0/apis-c.xml 2008-10-03 16:54:16 UTC (rev 11975)
Changed blocks: 5, Lines Added: 66, Lines Deleted: 19; 5254 bytes
@@ -5873,17 +5873,44 @@
<para>
Checks whether the connection to the server is working. If the
- connection has gone down, an attempt to reconnect is made unless
- auto-reconnect is disabled.
+ connection has gone down and auto-reconnect is enabled an
+ attempt to reconnect is made. If the connection is down and
+ auto-reconnect is disabled,
+ <function role="capi">mysql_ping()</function> returns an error.
</para>
<para>
- This function can be used by clients that remain idle for a long
- while, to check whether the server has closed the connection and
- reconnect if necessary.
+ Auto-reconnect is enabled by default before MySQL 5.0.3 and
+ enabled from 5.0.3 on. To enable auto-connect, call
+ <function role="capi">mysql_options()</function> with the
+ <literal>MYSQL_OPT_RECONNECT</literal> option. For details, see
+ <xref linkend="mysql-options"/>.
</para>
<para>
+ <function role="capi">mysql_ping()</function> can be used by
+ clients that remain idle for a long while, to check whether the
+ server has closed the connection and reconnect if necessary.
+ </para>
+
+ <para>
+ If <function role="capi">mysql_ping()</function>) does cause a
+ reconnect, there is no explicit indication of it. To determine
+ whether a reconnect occurs, call
+ <function role="capi">mysql_thread_id()</function> to get the
+ original connection identifier before calling
+ <function role="capi">mysql_ping()</function>, and then call
+ <function role="capi">mysql_thread_id()</function> again to see
+ whether the identifier has changed.
+ </para>
+
+ <para>
+ If reconnect occurs, some characteristics of the connection will
+ have been reset. For details about these characteristics, see
+ <xref linkend="auto-reconnect"/>.
+ </para>
+
+ <para>
<emphasis role="bold">Return Values</emphasis>
</para>
@@ -13544,14 +13571,14 @@
<section id="auto-reconnect">
- <title>Controlling Automatic Reconnect Behavior</title>
+ <title>Controlling Automatic Reconnection Behavior</title>
<para>
- The MySQL client library can perform an automatic reconnect to the
- server if it finds that the connection is down when you attempt to
- send a statement to the server to be executed. In this case, the
- library tries once to reconnect to the server and send the
- statement again.
+ The MySQL client library can perform an automatic reconnection to
+ the server if it finds that the connection is down when you
+ attempt to send a statement to the server to be executed. In this
+ case, the library tries once to reconnect to the server and send
+ the statement again.
</para>
<para>
@@ -13576,6 +13603,14 @@
</para>
<para>
+ If the connection has gone down, the
+ <function role="capi">mysql_ping()</function> function performs a
+ reconnect if auto-reconnect is enabled. If auto-reconnect is
+ disabled, <function role="capi">mysql_ping()</function> returns an
+ error instead.
+ </para>
+
+ <para>
Some client programs might provide the capability of controlling
automatic reconnection. For example, <command>mysql</command>
reconnects by default, but the <option>--skip-reconnect</option>
@@ -13583,6 +13618,17 @@
</para>
<para>
+ If an automatic reconnection does occur (for example, as a result
+ of calling <function role="capi">mysql_ping()</function>), there
+ is no explicit indication of it. To check for reconnection, call
+ <function role="capi">mysql_thread_id()</function> to get the
+ original connection identifier before calling
+ <function role="capi">mysql_ping()</function>, and then call
+ <function role="capi">mysql_thread_id()</function> again to see
+ whether the identifier has changed.
+ </para>
+
+ <para>
Automatic reconnection can be convenient because you need not
implement your own reconnect code, but if a reconnection does
occur, several aspects of the connection state are reset and your
@@ -13653,16 +13699,17 @@
</para>
</listitem>
- <listitem>
- <para>
- <function role="capi">mysql_ping()</function> does not attempt
- a reconnection if the connection is down. It returns an error
- instead.
- </para>
- </listitem>
-
</itemizedlist>
+ <para>
+ If the connection drops, it is possible that the session
+ associated with the connection on the server side will still be
+ running if the server has not yet detected that the client is no
+ longer connected. In this case, any locks held by the original
+ connection still belong to that session, so you may want to kill
+ it by calling <function role="capi">mysql_kill()</function>.
+ </para>
+
</section>
<section id="c-api-problems">
Modified: trunk/refman-5.1/apis-c.xml
===================================================================
--- trunk/refman-5.1/apis-c.xml 2008-10-03 15:50:44 UTC (rev 11974)
+++ trunk/refman-5.1/apis-c.xml 2008-10-03 16:54:16 UTC (rev 11975)
Changed blocks: 5, Lines Added: 65, Lines Deleted: 19; 5192 bytes
@@ -5929,17 +5929,43 @@
<para>
Checks whether the connection to the server is working. If the
- connection has gone down, an attempt to reconnect is made unless
- auto-reconnect is disabled.
+ connection has gone down and auto-reconnect is enabled an
+ attempt to reconnect is made. If the connection is down and
+ auto-reconnect is disabled,
+ <function role="capi">mysql_ping()</function> returns an error.
</para>
<para>
- This function can be used by clients that remain idle for a long
- while, to check whether the server has closed the connection and
- reconnect if necessary.
+ Auto-reconnect is disabled by default. To enable it, call
+ <function role="capi">mysql_options()</function> with the
+ <literal>MYSQL_OPT_RECONNECT</literal> option. For details, see
+ <xref linkend="mysql-options"/>.
</para>
<para>
+ <function role="capi">mysql_ping()</function> can be used by
+ clients that remain idle for a long while, to check whether the
+ server has closed the connection and reconnect if necessary.
+ </para>
+
+ <para>
+ If <function role="capi">mysql_ping()</function>) does cause a
+ reconnect, there is no explicit indication of it. To determine
+ whether a reconnect occurs, call
+ <function role="capi">mysql_thread_id()</function> to get the
+ original connection identifier before calling
+ <function role="capi">mysql_ping()</function>, and then call
+ <function role="capi">mysql_thread_id()</function> again to see
+ whether the identifier has changed.
+ </para>
+
+ <para>
+ If reconnect occurs, some characteristics of the connection will
+ have been reset. For details about these characteristics, see
+ <xref linkend="auto-reconnect"/>.
+ </para>
+
+ <para>
<emphasis role="bold">Return Values</emphasis>
</para>
@@ -13617,14 +13643,14 @@
<section id="auto-reconnect">
- <title>Controlling Automatic Reconnect Behavior</title>
+ <title>Controlling Automatic Reconnection Behavior</title>
<para>
- The MySQL client library can perform an automatic reconnect to the
- server if it finds that the connection is down when you attempt to
- send a statement to the server to be executed. In this case, the
- library tries once to reconnect to the server and send the
- statement again.
+ The MySQL client library can perform an automatic reconnection to
+ the server if it finds that the connection is down when you
+ attempt to send a statement to the server to be executed. In this
+ case, the library tries once to reconnect to the server and send
+ the statement again.
</para>
<para>
@@ -13646,6 +13672,14 @@
</para>
<para>
+ If the connection has gone down, the
+ <function role="capi">mysql_ping()</function> function performs a
+ reconnect if auto-reconnect is enabled. If auto-reconnect is
+ disabled, <function role="capi">mysql_ping()</function> returns an
+ error instead.
+ </para>
+
+ <para>
Some client programs might provide the capability of controlling
automatic reconnection. For example, <command>mysql</command>
reconnects by default, but the <option>--skip-reconnect</option>
@@ -13653,6 +13687,17 @@
</para>
<para>
+ If an automatic reconnection does occur (for example, as a result
+ of calling <function role="capi">mysql_ping()</function>), there
+ is no explicit indication of it. To check for reconnection, call
+ <function role="capi">mysql_thread_id()</function> to get the
+ original connection identifier before calling
+ <function role="capi">mysql_ping()</function>, and then call
+ <function role="capi">mysql_thread_id()</function> again to see
+ whether the identifier has changed.
+ </para>
+
+ <para>
Automatic reconnection can be convenient because you need not
implement your own reconnect code, but if a reconnection does
occur, several aspects of the connection state are reset and your
@@ -13723,16 +13768,17 @@
</para>
</listitem>
- <listitem>
- <para>
- <function role="capi">mysql_ping()</function> does not attempt
- a reconnection if the connection is down. It returns an error
- instead.
- </para>
- </listitem>
-
</itemizedlist>
+ <para>
+ If the connection drops, it is possible that the session
+ associated with the connection on the server side will still be
+ running if the server has not yet detected that the client is no
+ longer connected. In this case, any locks held by the original
+ connection still belong to that session, so you may want to kill
+ it by calling <function role="capi">mysql_kill()</function>.
+ </para>
+
</section>
<section id="c-api-problems">
Modified: trunk/refman-6.0/apis-c.xml
===================================================================
--- trunk/refman-6.0/apis-c.xml 2008-10-03 15:50:44 UTC (rev 11974)
+++ trunk/refman-6.0/apis-c.xml 2008-10-03 16:54:16 UTC (rev 11975)
Changed blocks: 5, Lines Added: 65, Lines Deleted: 19; 5192 bytes
@@ -5866,17 +5866,43 @@
<para>
Checks whether the connection to the server is working. If the
- connection has gone down, an attempt to reconnect is made unless
- auto-reconnect is disabled.
+ connection has gone down and auto-reconnect is enabled an
+ attempt to reconnect is made. If the connection is down and
+ auto-reconnect is disabled,
+ <function role="capi">mysql_ping()</function> returns an error.
</para>
<para>
- This function can be used by clients that remain idle for a long
- while, to check whether the server has closed the connection and
- reconnect if necessary.
+ Auto-reconnect is disabled by default. To enable it, call
+ <function role="capi">mysql_options()</function> with the
+ <literal>MYSQL_OPT_RECONNECT</literal> option. For details, see
+ <xref linkend="mysql-options"/>.
</para>
<para>
+ <function role="capi">mysql_ping()</function> can be used by
+ clients that remain idle for a long while, to check whether the
+ server has closed the connection and reconnect if necessary.
+ </para>
+
+ <para>
+ If <function role="capi">mysql_ping()</function>) does cause a
+ reconnect, there is no explicit indication of it. To determine
+ whether a reconnect occurs, call
+ <function role="capi">mysql_thread_id()</function> to get the
+ original connection identifier before calling
+ <function role="capi">mysql_ping()</function>, and then call
+ <function role="capi">mysql_thread_id()</function> again to see
+ whether the identifier has changed.
+ </para>
+
+ <para>
+ If reconnect occurs, some characteristics of the connection will
+ have been reset. For details about these characteristics, see
+ <xref linkend="auto-reconnect"/>.
+ </para>
+
+ <para>
<emphasis role="bold">Return Values</emphasis>
</para>
@@ -13524,14 +13550,14 @@
<section id="auto-reconnect">
- <title>Controlling Automatic Reconnect Behavior</title>
+ <title>Controlling Automatic Reconnection Behavior</title>
<para>
- The MySQL client library can perform an automatic reconnect to the
- server if it finds that the connection is down when you attempt to
- send a statement to the server to be executed. In this case, the
- library tries once to reconnect to the server and send the
- statement again.
+ The MySQL client library can perform an automatic reconnection to
+ the server if it finds that the connection is down when you
+ attempt to send a statement to the server to be executed. In this
+ case, the library tries once to reconnect to the server and send
+ the statement again.
</para>
<para>
@@ -13553,6 +13579,14 @@
</para>
<para>
+ If the connection has gone down, the
+ <function role="capi">mysql_ping()</function> function performs a
+ reconnect if auto-reconnect is enabled. If auto-reconnect is
+ disabled, <function role="capi">mysql_ping()</function> returns an
+ error instead.
+ </para>
+
+ <para>
Some client programs might provide the capability of controlling
automatic reconnection. For example, <command>mysql</command>
reconnects by default, but the <option>--skip-reconnect</option>
@@ -13560,6 +13594,17 @@
</para>
<para>
+ If an automatic reconnection does occur (for example, as a result
+ of calling <function role="capi">mysql_ping()</function>), there
+ is no explicit indication of it. To check for reconnection, call
+ <function role="capi">mysql_thread_id()</function> to get the
+ original connection identifier before calling
+ <function role="capi">mysql_ping()</function>, and then call
+ <function role="capi">mysql_thread_id()</function> again to see
+ whether the identifier has changed.
+ </para>
+
+ <para>
Automatic reconnection can be convenient because you need not
implement your own reconnect code, but if a reconnection does
occur, several aspects of the connection state are reset and your
@@ -13630,16 +13675,17 @@
</para>
</listitem>
- <listitem>
- <para>
- <function role="capi">mysql_ping()</function> does not attempt
- a reconnection if the connection is down. It returns an error
- instead.
- </para>
- </listitem>
-
</itemizedlist>
+ <para>
+ If the connection drops, it is possible that the session
+ associated with the connection on the server side will still be
+ running if the server has not yet detected that the client is no
+ longer connected. In this case, any locks held by the original
+ connection still belong to that session, so you may want to kill
+ it by calling <function role="capi">mysql_kill()</function>.
+ </para>
+
</section>
<section id="c-api-problems">
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r11975 - in trunk: . refman-4.1 refman-5.0 refman-5.1 refman-6.0 | paul.dubois | 3 Oct |
