Author: timbo
Date: Sun May 13 14:17:43 2007
New Revision: 9563
Modified:
dbi/trunk/Changes
dbi/trunk/lib/DBD/Gofer/Policy/Base.pm
dbi/trunk/lib/DBI/Gofer/Execute.pm
Log:
Minor doc tweaks
Modified: dbi/trunk/Changes
==============================================================================
--- dbi/trunk/Changes (original)
+++ dbi/trunk/Changes Sun May 13 14:17:43 2007
@@ -8,12 +8,6 @@
Assorted TODO notes:
-Policy principle:
- Designed to influence behaviour of unaltered programs
- ie go_* attributes take precidence over policy
- on the basis that if you can alter the code to add go_* attributes
- then you can also put your required logic at that place
-
Move post-request cleanup into separate method and enable hooks so
it can be done after the response has been sent
@@ -21,7 +15,6 @@
return current executor stats as an attribute - handy for tests
only fetch one result set - handy for Sybase/MSSQL users
will accept streamed resultsets
-Pedantic policy should force a fresh connect each time - add new policy item
Add attr-passthru to prepare()? ie for gofer cache control & ReadOnly
Terminology for client and server ends
Document user/passwd issues at the various levels of the gofer stack
@@ -35,11 +28,12 @@
prepare(...,{ Err=>\my $isolated_err, ...})
Move _new_sth to DBI::db::_new_sth (leave alias) and implement in C
+Implement FETCH_many() in C
Or call _new_child and move to DBI::common?
Add trace modules that just records the last N trace messages into an array
and prepends them to any error message.
-=head2 Changes in DBI 1.56 (svn rev XXX), 11th May 2007
+=head2 Changes in DBI 1.56 (svn rev 9561), 13th May 2007
Fixed printf arg warnings thanks to JDHEDDEN.
Fixed returning driver-private sth attributes via gofer.
@@ -52,10 +46,7 @@
Added DBI_GOFER_RANDOM env var that can be use to trigger random
failures and delays when executing gofer requests. Designed to help
test automatic retry on failures and timeout handling.
-
- Add way for gofer executor config to enable extra dbh/sth to be returned
with responses.
- Add $h->FETCH_many(@attrib_names) method.
-
+ Added lots more docs to all the DBD::Gofer and DBI::Gofer classes.
=head2 Changes in DBI 1.55 (svn rev 9504), 4th May 2007
Modified: dbi/trunk/lib/DBD/Gofer/Policy/Base.pm
==============================================================================
--- dbi/trunk/lib/DBD/Gofer/Policy/Base.pm (original)
+++ dbi/trunk/lib/DBD/Gofer/Policy/Base.pm Sun May 13 14:17:43 2007
@@ -93,20 +93,60 @@
=head1 DESCRIPTION
-The Base policy is not used directly. You should use a policy class derived
from it.
+DBD::Gofer can be configured via a 'policy' mechanism that allows you to
+fine-tune the number of round-trips to the Gofer server. The policies are
+grouped into classes (which may be subclassed) and referenced by the name of
+the class.
+
+The L<DBD::Gofer::Policy::Base> class is the base class for all the policy
+classes and describes all the individual policy items.
-Policies included with DBD::Gofer include:
+The Base policy is not used directly. You should use a policy class derived
from it.
-L<DBD::Gofer::Policy::pedantic> - strictest but slowest
+=head1 POLICY CLASSES
-L<DBD::Gofer::Policy::classic> - reasonable strictness and speed - the default
+Three policy classes are supplied with DBD::Gofer:
+
+L<DBD::Gofer::Policy::pedantic> is most 'transparent' but slowest because it
+makes more round-trips to the Gofer server.
+
+L<DBD::Gofer::Policy::classic> is a reasonable compromise - it's the default
policy.
+
+L<DBD::Gofer::Policy::rush> is fastest, but may require code changes in your
applications.
+
+Generally the default C<classic> policy is fine. When first testing an existing
+application with Gofer it is a good idea to start with the C<pedantic> policy
+first and then switch to C<classic> or a custom policy, for final testing.
-L<DBD::Gofer::Policy::rush> - least strictness, fewest round-trips
+=head1 POLICY ITEMS
These are temporary docs: See the source code for list of policies and their
defaults.
In a future version the policies and their defaults will be defined in the pod
and parsed out at load-time.
+See the source code to this module for more details.
+
+=head1 POLICY CUSTOMIZATION
+
+XXX This area of DBD::Gofer is subject to change.
+
+There are three ways to customize policies:
+
+Policy classes are designed to influence the overall behaviour of DBD::Gofer
+with existing, unaltered programs, so they work in a reasonably optimal way
+without requiring code changes. You can implement new policy classes as
+subclasses of existing policies.
+
+In many cases individual policy items can be overridden on a case-by-case basis
+within your application code. You do this by passing a corresponding
+C<<go_<policy_name>>> attribute into DBI methods by your application code.
+This let's you fine-tune the behaviour for special cases.
+
+The policy items are implemented as methods. In many cases the methods are
+passed parameters relating to the DBD::Gofer code being executed. This means
+the policy can implement dynamic behaviour that varies depending on the
+particular circumstances, such as the particular statement being executed.
+
=head1 AUTHOR
Tim Bunce, L<http://www.linkedin.com/in/timbunce>
Modified: dbi/trunk/lib/DBI/Gofer/Execute.pm
==============================================================================
--- dbi/trunk/lib/DBI/Gofer/Execute.pm (original)
+++ dbi/trunk/lib/DBI/Gofer/Execute.pm Sun May 13 14:17:43 2007
@@ -708,6 +708,21 @@
If true, then only the first result set will be fetched and returned in the
response.
+=head2 forced_response_attributes
+
+A reference to a data structure that can specify extra attributes to be
returned in responses.
+
+ forced_response_attributes => {
+ DriverName => {
+ dbh => [ qw(dbh_attrib_name) ],
+ sth => [ qw(sth_attrib_name) ],
+ },
+ },
+
+This can be useful in cases where the driver has not implemented the
+private_attribute_info() method and DBI::Gofer::Execute's own fallback list of
+private attributes doesn't include the driver or attributes you need.
+
=head2 track_recent
If set, specifies the number of recent requests and responses that should be
@@ -773,7 +788,7 @@
});
will cause the do() method to fail for 0.01% of calls, and the execute()
method to
-fail for 0.01% of calls and be delayed by 60 seconds on 1% of calls.
+fail 0.01% of calls and be delayed by 60 seconds on 1% of calls.
=head1 AUTHOR
