This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).

LWP::ConnCache(3)                    User Contributed Perl Documentation                   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_capacity'.  If specified it initialize 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 specified type that can be cached.  The
           $type will typically be a short string like "http" or "ftp".

       $cache->drop( [$checker, [$reason]] )
           Drop connections by some criteria.  The $checker argument is a subroutine that is called for each
           connection.  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 connections 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 argument.  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.

SEE ALSO
       LWP::UserAgent

COPYRIGHT
       Copyright 2001 Gisle Aas.

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



perl v5.8.8                                      2004-04-09                                LWP::ConnCache(3)