| Subject: | PATCH: numerous documentation improvements |
The attached patch adds numerous documentation improvements, including:
- internal docs for _execute_with_timeout
- documenting how to disable the connect and execute timeouts
- documenting a general purpose failover_test function
Mark
| Subject: | dbix-ha-docs.patch |
Wed Feb 14 16:11:51 EST 2007 mark@summersault.com
* A variety of doc patches
diff -rN -u old-DBIx-HA-0.99/Changes new-DBIx-HA-0.99/Changes
--- old-DBIx-HA-0.99/Changes 2007-02-14 16:12:42.000000000 -0500
+++ new-DBIx-HA-0.99/Changes 2007-02-14 16:12:42.000000000 -0500
@@ -1,5 +1,7 @@
Revision history for Perl extension DBIx::HA.
+ - Numerous documentation improvements (Mark Stosberg)
+
0.99 Wed Oct 04 18:18:00 2006
- Fix for Apache children always starting at index 0 and
overwriting shared file if under app failover.
diff -rN -u old-DBIx-HA-0.99/lib/DBIx/HA.pm new-DBIx-HA-0.99/lib/DBIx/HA.pm
--- old-DBIx-HA-0.99/lib/DBIx/HA.pm 2007-02-14 16:12:42.000000000 -0500
+++ new-DBIx-HA-0.99/lib/DBIx/HA.pm 2007-02-14 16:12:42.000000000 -0500
@@ -535,6 +535,28 @@
return $res;
}
+=begin private
+
+=head2
+
+ ($execute_result,$timeout_triggered) = _execute_with_timeout($dsn,$sth);
+
+Calls "execute" on a DBI statement handle, and handles a possible timeout of the query.
+
+Args:
+ $dsn: a key in our internal lookup table of connection details
+ $sth: DBI statement handle
+
+Returns:
+ - result of execute() call
+ - boolean, true if timeout was triggered.
+
+
+=end private
+
+=cut
+
+
sub _execute_with_timeout {
my $dsn = shift;
my $sth = shift;
@@ -771,14 +793,16 @@
=item connecttimeout ( DEFAULT: 5 )
-timeout for connecting to a datasource, in seconds.
+Timeout for connecting to a datasource, in seconds. A value of 0 disables this timeout.
=item executetimeout ( DEFAULT: 10 )
-timeout for execution of a statement, in seconds. If the timeout is triggered,
+Timeout for execution of a statement, in seconds. If the timeout is triggered,
the database handle is deleted and a new connect is tried. If the connect
succeeds, we assume that the problem is with a runaway SQL statement or bad
-indexing. If the connect fails, then we fail over.
+indexing. If the connect fails, then we fail over. A value of 0 disables this timeout.
+
+
=item callback_function ( DEFAULT: I<none> )
@@ -787,22 +811,28 @@
=item failtest_function ( DEFAULT: sub{0} )
-reference to a function to call to test if a DBI error is a candidate for
-failover or not.
-Input is ($ErrorID, $ErrorString)
+Reference to a function to call to test if a DBI error is a candidate for
+failover or not. This is only triggered when a call to C<execute()> returns
+an undefined value.
+
+Input is ($DBI::err, $DBI::errstr). These correspond to the native driver error
+code and string values. See the docs for your database driver and L<DBI> for
+details.
+
Output is boolean: If true, then we'll consider the error a critical
condition, ok to failover. If false, then DBIx::HA will not act on it
and pass it straight through to the client.
This Fail Test Function (FTF) function is extremely important for the proper
functioning of DBIx::HA. You must be careful in defining it
-precisely, based on the database engine that you are using. As a
-convenience to the user, DBIx::HA defines some sample functions that
-you can use. At this time, only the following samples are defined:
+precisely, based on the database engine that you are using. A sample
+function for Sybase is included:
+
+ failtest_function => \&DBIx::HA::FTF_SybaseASE,
- DBIx::HA::FTF_SybaseASE
+To consider any error a reason to failover, you could use the following:
-Example use is in the synopsis
+ failtest_function => sub {1},
=back