DBD::Gofer::Policy::Base(3) User Contributed Perl Documentation DBD::Gofer::Policy::Base(3)NAME
DBD::Gofer::Policy::Base - Base class for DBD::Gofer policies
SYNOPSIS
$dbh = DBI->connect("dbi:Gofer:transport=...;policy=...", ...)
DESCRIPTION
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 DBD::Gofer::Policy::Base class is the base class for all the policy classes and describes all the individual policy items.
The Base policy is not used directly. You should use a policy class derived from it.
POLICY CLASSES
Three policy classes are supplied with DBD::Gofer:
DBD::Gofer::Policy::pedantic is most 'transparent' but slowest because it makes more round-trips to the Gofer server.
DBD::Gofer::Policy::classic is a reasonable compromise - it's the default policy.
DBD::Gofer::Policy::rush is fastest, but may require code changes in your applications.
Generally the default "classic" policy is fine. When first testing an existing application with Gofer it is a good idea to start with the
"pedantic" policy first and then switch to "classic" or a custom policy, for final testing.
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.
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 "<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.
AUTHOR
Tim Bunce, <http://www.tim.bunce.name>
LICENCE AND COPYRIGHT
Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
perl v5.12.1 2007-10-16 DBD::Gofer::Policy::Base(3)
Check Out this Related Man Page
DBD::Gofer::Transport::Base(3) User Contributed Perl Documentation DBD::Gofer::Transport::Base(3)NAME
DBD::Gofer::Transport::Base - base class for DBD::Gofer client transports
SYNOPSIS
my $remote_dsn = "..."
DBI->connect("dbi:Gofer:transport=...;url=...;timeout=...;retry_limit=...;dsn=$remote_dsn",...)
or, enable by setting the DBI_AUTOPROXY environment variable:
export DBI_AUTOPROXY='dbi:Gofer:transport=...;url=...'
which will force all DBI connections to be made via that Gofer server.
DESCRIPTION
This is the base class for all DBD::Gofer client transports.
ATTRIBUTES
Gofer transport attributes can be specified either in the attributes parameter of the connect() method call, or in the DSN string. When
used in the DSN string, attribute names don't have the "go_" prefix.
go_dsn
The full DBI DSN that the Gofer server should connect to on your behalf.
When used in the DSN it must be the last element in the DSN string.
go_timeout
A time limit for sending a request and receiving a response. Some drivers may implement sending and receiving as separate steps, in which
case (currently) the timeout applies to each separately.
If a request needs to be resent then the timeout is restarted for each sending of a request and receiving of a response.
go_retry_limit
The maximum number of times an request may be retried. The default is 2.
go_retry_hook
This subroutine reference is called, if defined, for each response received where $response->err is true.
The subroutine is pass three parameters: the request object, the response object, and the transport object.
If it returns an undefined value then the default retry behaviour is used. See "RETRY ON ERROR" below.
If it returns a defined but false value then the request is not resent.
If it returns true value then the request is resent, so long as the number of retries does not exceed "go_retry_limit".
RETRY ON ERROR
The default retry on error behaviour is:
- Retry if the error was due to DBI_GOFER_RANDOM. See L<DBI::Gofer::Execute>.
- Retry if $request->is_idempotent returns true. See L<DBI::Gofer::Request>.
A retry won't be allowed if the number of previous retries has reached "go_retry_limit".
TRACING
Tracing of gofer requests and responses can be enabled by setting the "DBD_GOFER_TRACE" environment variable. A value of 1 gives a
reasonably compact summary of each request and response. A value of 2 or more gives a detailed, and voluminous, dump.
The trace is written using DBI->trace_msg() and so is written to the default DBI trace output, which is usually STDERR.
METHODS
This section is currently far from complete.
response_retry_preference
$retry = $transport->response_retry_preference($request, $response);
The response_retry_preference is called by DBD::Gofer when considering if a request should be retried after an error.
Returns true (would like to retry), false (must not retry), undef (no preference).
If a true value is returned in the form of a CODE ref then, if DBD::Gofer does decide to retry the request, it calls the code ref passing
$retry_count, $retry_limit. Can be used for logging and/or to implement exponential backoff behaviour. Currently the called code must
return using "return;" to allow for future extensions.
AUTHOR
Tim Bunce, <http://www.tim.bunce.name>
LICENCE AND COPYRIGHT
Copyright (c) 2007-2008, Tim Bunce, Ireland. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
SEE ALSO
DBD::Gofer, DBI::Gofer::Request, DBI::Gofer::Response, DBI::Gofer::Execute.
and some example transports:
DBD::Gofer::Transport::stream
DBD::Gofer::Transport::http
DBI::Gofer::Transport::mod_perl
perl v5.16.2 2011-09-09 DBD::Gofer::Transport::Base(3)