view release on metacpan or  search on metacpan

lib/Apache/DBI/Cache.pod  view on Meta::CPAN

=over 2

=item * B<plugin>

loads a plugin, see also L</"PLUGINS"> below. The plugin can be specified
as a 3-element array or by name. In the second case the C<import> simply
C<use>s the module. This option can be given multiple times.

=item * B<use_bdb>, B<bdb_env> and B<bdb_memcache>

Apache::DBI::Cache can use L<BerleleyDB> as a shared memory implementation
to maintain statistics for a group of processes instead of a single process.

C<use_bdb> specify whether to use BerkeleyDB or not. If ommitted
Apache::DBI::Cache will try to load and use BerkeleyDB. If that fails it
silently provides per process statistics. If C<use_bdb> is true
Apache::DBI::Cache dies if it cannot use BerkeleyDB. If C<use_bdb> is false
per process statistics are maintained and BerkeleyDB is not used.

C<bdb_env> specifies a path to a directory where BerkeleyDB can put
it's temporary files. If omitted C</tmp/Apache::DBI::Cache> is used.
The parent directory of this directory must exists and be writeable.

C<bdb_memcache> specifies the size of the shared memory segment that
is allocated by BerkeleyDB. Depending on the number of handles in your
configuration a few kilobytes are enough. If omitted 20 kB are used.

C<bdb_env> and C<bdb_memcache> can also be specified by the
C<APACHE_DBI_CACHE_ENVPATH> and C<APACHE_DBI_CACHE_CACHESIZE> environment
variables.

=item * B<debug>

set a debug level. Under mod_perl this is almost irrelevant, see L</"logger">
below.

=item * B<logger>

here a logger function can be specified. It is called with the
message verbosity level as the first parameter. The remaining parameters
are concatenated to build the actual message.

Currently there are 2 verbosity levels used 1 and 2. 0 is reserved for real
errors. 1 mentions that the module has been initialized. 2 rattle off
normal processing messages.

Apache::DBI::Cache provides 2 logger functions. One is controlled by the
C<debug> level setting (see above). A message is printed to STDERR if
it's level is equal or greater the current debug level.

The other logger is used when running under mod_perl. It is mainly controlled
by the Apache C<LogLevel> setting. Messages at level 0 are printed as
C<< $log->error >>, level 1 as C<< $log->info >> and level 2 as
C<< $log->debug >>. For level 2 messages additionally the current debug
level is checked to be greater or equal 2.

=item * B<delimiter>

Here the internal key delimiter can be changed. It defaults to C<\1>.
Changing it is necessary only when your DSN, username or password contain
it or to provide more readable debugging messages.

=back

=item B<statistics>

returns a reference to the statistics hash. If BerkeleyDB is used it is
tied to L<BerkeleyDB::Btree>.

=item B<statistics_as_html>

returns a reference to an array of HTML fragments. If mod_perl and
Apache::Status or Apache::Status2 is used the output of this function
is shown under http://HOST/STATUS/URI?DBI_conn.

=item B<plugin( 'name', \&mangle, \&setup )>

installs a new plugin, see L</"PLUGINS"> below. If a plugin for the
specified database type was already installed it is returned as a
2-element list:

 ($old_mangle, $old_setup)=
   plugin( 'name', \&new_mangle, \&new_setup );

If called with an name only the current plugin is returned:

 ($old_mangle, $old_setup)=plugin( 'name' );

To delete a plugin call

 ($old_mangle, $old_setup)=plugin( 'name', undef, undef );

=item B<connect_on_init>

call this function multiple times with parameters you would pass to
C<< DBI->connect >> before calling C<Apache::DBI::Cache::init>, i.e.
in your C<startup.pl>. Then C<init> will establish all these connections.

=item B<init>

This function is called once per child process to initialize
Apache::DBI::Cache. If mod_perl is used this is done automatically
in a PerlChildInitHandler

=item B<finish>

This function must be called before a process is going to terminate. Under
mod_perl it is automatically called in a PerlChildExitHandler.

As of version 0.08 calling this function is optional.

=item B<undef_at_request_cleanup( \$dbh1, \$dbh2, ... )>

When an application uses global variables to store handles they probably
won't be reused because a global variable is ..., well global. This can
be fixed by explicitly undefining these handles at request cleanup or
by using this function. It simply collects all handle references passed in
between 2 calls to C<Apache::DBI::Cache::request_cleanup>. When
C<Apache::DBI::Cache::request_cleanup> is called all these handles are
undefined. The first call to this function during a request cycle