lwp::conncache(3)

NAME

LWP::ConnCache - Connection cache manager

NOTE

This module is experimental. Details of its interface is
likely to change in the future.

SYNOPSIS

use LWP::ConnCache;
my $cache = LWP::ConnCache->new;
$cache->deposit($type, $key, $sock);
$sock = $cache->withdraw($type, $key);

DESCRIPTION

The "LWP::ConnCache" class is the standard connection
cache manager for LWP::UserAgent.

The following basic methods are provided:

$cache = LWP::ConnCache->new( %options ): This method constructs a new "LWP::ConnCache" object.
The only option currently accepted is 'total_capac
ity'. If specified it initalize the total_capacity
option. It defaults to the value 1.
$cache->total_capacity( [$num_connections] ): Get/sets the number of connection that will be cached.
Connections will start to be dropped when this limit
is reached. If set to 0, then all connections are
immediately dropped. If set to "undef", then there is
no limit.
$cache->capacity($type, [$num_connections] ): Get/set a limit for the number of connections of the
specifed type that can be cached. The $type will typ
ically be a short string like "http" or "ftp".
$cache->drop( [$checker, [$reason]] ): Drop connections by some criteria. The $checker argu
ment is a subroutine that is called for each connec
tion. If the routine returns a TRUE value then the
connection is dropped. The routine is called with
($conn, $type, $key, $deposit_time) as arguments.; Shortcuts: If the $checker argument is absent (or
"undef") all cached connections are dropped. If the
$checker is a number then all connections untouched
that the given number of seconds or more are dropped.
If $checker is a string then all connections of the
given type are dropped.; The $reason argument is passed on to the dropped() method.
$cache->prune: Calling this method will drop all connections that are
dead. This is tested by calling the ping() method on
the connections. If the ping() method exists and
returns a FALSE value, then the connection is dropped.
$cache->get_types: This returns all the 'type' fields used for the
currently cached connections.
$cache->get_connections( [$type] ): This returns all connection objects of the specified
type. If no type is specified then all connections
are returned. In scalar context the number of cached
connections of the specified type is returned.
The following methods are called by low-level protocol modules to try to save away connections and to get them back.
$cache->deposit($type, $key, $conn): This method adds a new connection to the cache. As a
result other already cached connections might be
dropped. Multiple connections with the same
$type/$key might added.
$conn = $cache->withdraw($type, $key): This method tries to fetch back a connection that was
previously deposited. If no cached connection with
the specified $type/$key is found, then "undef" is
returned. There is not guarantee that a deposited
connection can be withdrawn, as the cache manger is
free to drop connections at any time.
The following methods are called internally. Subclasses might want to override them.
$conn->enforce_limits([$type]): This method is called with after a new connection is
added (deposited) in the cache or capacity limits are
adjusted. The default implementation drops connec
tions until the specified capacity limits are not
exceeded.
$conn->dropping($conn_record, $reason): This method is called when a connection is dropped.
The record belonging to the dropped connection is
passed as the first argument and a string describing
the reason for the drop is passed as the second argu
ment. The default implementation makes some noise if
the $LWP::ConnCache::DEBUG variable is set and nothing
more.

SUBCLASSING

For specialized cache policy it makes sense to subclass
"LWP::ConnCache" and perhaps override the deposit(), enforce_limits() and dropping() methods.

The object itself is a hash. Keys prefixed with "cc_" are
reserved for the base class.

COPYRIGHT

This library is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.

docs.sk

comprehensive documentation repository

In section