Author: wyoung
Date: Wed Apr 15 07:35:38 2009
New Revision: 2502
URL: http://svn.gna.org/viewcvs/mysqlpp?rev=2502&view=rev
Log:
Second pass through the new connection timeout section of the Tutorial
Modified:
trunk/doc/userman/tutorial.dbx
Modified: trunk/doc/userman/tutorial.dbx
URL:
http://svn.gna.org/viewcvs/mysqlpp/trunk/doc/userman/tutorial.dbx?rev=2502&r1=2501&r2=2502&view=diff
==============================================================================
--- trunk/doc/userman/tutorial.dbx (original)
+++ trunk/doc/userman/tutorial.dbx Wed Apr 15 07:35:38 2009
@@ -1210,60 +1210,82 @@
<title>Dealing with Connection Timeouts</title>
<para>By default, current MySQL servers have an 8 hour idle
- timeout on connections. The most common way to run into this
- problem is when you have a program that runs continually, but you
- keep finding that it dies overnight or over the weekend because
- no one is making it issue queries. The MySQL server closes the
- connection after the configured idle timeout to free up resources,
- because a networked program can never be sure that the remote
- peer is still there when no data is being transferred.</para>
-
- <para>You cannot detect this by calling
- <methodname>Connection::connected()</methodname>. If
+ timeout on connections. This is not a problem if your program
+ never has to run for more than 8 hours or reliably queries the
+ database more often than that. And, it’s a good thing for
+ the database server, because even an idle connection takes up
+ server resources.</para>
+
+ <para>Many programs must run continually, however, and may
+ experience long idle periods, such as nights and weekends
+ when no one is around to make the program issue database
+ queries. It’s therefore common for people writing such
+ programs to get a bug report from the field complaining that the
+ program died overnight or over a long weekend, usually with some
+ error message about the database server going away. They then check
+ the DB server, find that it’s still running and never did
+ restart and scratch their heads wondering what happened. What
+ happened is that the server’s connection idle timeout
+ expired, so it closed the connection to the client.</para>
+
+ <para>You cannot detect this condition by calling
+ <methodname>Connection::connected()</methodname>. When
that returns <symbol>true</symbol>, it just means
that either the connect-on-create constructor or the
<methodname>connect()</methodname> call succeeded and that we
haven’t observed the connection to be down since then.
- If the server closes the connection, you won’t know it
- until the next time you try to talk to it. This is simply due to
- the nature of network programming.</para>
+ When the database server closes an idle connection, you won’t
+ know it until after you try to issue a query. This is simply due
+ to the nature of network programming.</para>
<para>One way around this problem is to <ulink
url="http://dev.mysql.com/doc/refman/5.0/en/gone-away.html";>configure
- MySQL</ulink> to use a different timeout. This timeout is in
- seconds, so the default of 8 hours is 28,800 seconds. You could
- figure out the longest possible time that your program could be
- left idle. For instance, it could be left running over a long
- 4-day weekend, which is 345,600 seconds, which you could round
- up to 350,000 or 400,000 just to keep things simple.</para>
-
- <para>You can also change this parameter on a per-connection
- basis, too, by using MySQL++’s <ulink type="classref"
- url="ConnectTimeoutOption"/> <link linkend="connopts">connection
- option</link>.</para>
-
- <para>Another way to tackle this, if your program is asynchronous
- (i.e. doesn’t stay blocked forever waiting on I/O while idle)
- or uses <link linkend="threads">threads</link>, is to periodically
- call <methodname>Connection::ping()</methodname>. This sends
- the smallest possible amount of data to the database server,
- which will reset its idle timer. If the server responds,
- <methodname>ping()</methodname> returns <symbol>true</symbol>,
- so this also gives your program the ability to detect that
- the server has gone away before trying a query. Don’t
- ping the server too often, though, as it takes a tiny amount
- of processing capability to handle a ping, which can add up to
- a significant amount if done often enough by a client, or even
- just rarely by enough clients. When I do this, I just assume the
- database server is there, pinging it no more often than half the
- connection timeout. With the default of 8 hours, then, I’d
- ping between every 4 and 7 hours.</para>
-
- <para>An interesting variant is to ping the server before each
- query, or, better, before each group of queries within a larger
- operation. It has an advantage over pinging during idle time in
- that the client is about to use far more server resources to
- handle the query than it will take to handle the ping, so the
+ MySQL</ulink> to have a longer idle timeout. This timeout is
+ in seconds, so the default of 8 hours is 28,800 seconds. You
+ would want to figure out the longest possible time that your
+ program could be left idle, then pick a value somewhat longer
+ than that. For instance, you might decide that the longest
+ reasonable idle time is a long 4-day weekend — 345,600
+ seconds — which you could round up to 350,000 or 400,000
+ to allow for a little bit of additional idle time on either end
+ of that period.</para>
+
+ <para>Alternately, you can change this parameter on a
+ per-connection basis by using MySQL++’s <ulink
+ type="classref" url="ConnectTimeoutOption"/> <link
+ linkend="connopts">connection option</link>.</para>
+
+ <para>A completely different way to tackle this, if your program
+ doesn’t block forever waiting on I/O while idle, is to
+ periodically call <methodname>Connection::ping()</methodname>.
+
+ <footnote>
+ <para>Don’t ping the server too often! It takes a tiny
+ amount of processing capability to handle a ping, which can add
+ up to a significant amount if done often enough by a client, or
+ even just rarely by enough clients. Also, a lower ping frequency
+ can let your program ride through some types of network faults
+ — a switch reboot, for instance — without needing
+ a reconnect. I like to ping the DB server no more often than
+ half the connection timeout. With the default of 8 hours, then,
+ I’d ping between every 4 and 7 hours.</para>
+ </footnote>
+
+ This sends the smallest possible amount of data to the
+ database server, which will reset its idle timer and cause
+ it to respond, so <methodname>ping()</methodname> returns
+ <symbol>true</symbol>. If it returns <symbol>false</symbol>
+ instead, you know you need to reconnect to the server. Periodic
+ pinging is easiest to do if your program uses asynchronous I/O,
+ <link linkend="threads">threads</link>, or some kind of event
+ loop to ensure that you can call something periodically even
+ while the rest of the program has nothing to do.</para>
+
+ <para>An interesting variant on this strategy is to ping the server
+ before each query, or, better, before each group of queries within
+ a larger operation. It has an advantage over pinging during idle
+ time in that the client is about to use far more server resources
+ to handle the query than it will take to handle the ping, so the
ping time gets lost in the overhead. On the other hand, if the
client issues queries frequently when not idle, it can result
in a lot more pings than would happen if you just pinged every
_______________________________________________
Mysqlpp-commits mailing list
[email protected]
https://mail.gna.org/listinfo/mysqlpp-commits
