1LWP::ConnCache(3)     User Contributed Perl Documentation    LWP::ConnCache(3)
2
3
4

NAME

6       LWP::ConnCache - Connection cache manager
7

NOTE

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

SYNOPSIS

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

DESCRIPTION

19       The "LWP::ConnCache" class is the standard connection cache manager for
20       LWP::UserAgent.
21
22       The following basic methods are provided:
23
24       $cache = LWP::ConnCache->new( %options )
25           This method constructs a new "LWP::ConnCache" object.  The only
26           option currently accepted is 'total_capacity'.  If specified it
27           initialize the total_capacity option.  It defaults to the value 1.
28
29       $cache->total_capacity( [$num_connections] )
30           Get/sets the number of connection that will be cached.  Connections
31           will start to be dropped when this limit is reached.  If set to 0,
32           then all connections are immediately dropped.  If set to "undef",
33           then there is no limit.
34
35       $cache->capacity($type, [$num_connections] )
36           Get/set a limit for the number of connections of the specified type
37           that can be cached.  The $type will typically be a short string
38           like "http" or "ftp".
39
40       $cache->drop( [$checker, [$reason]] )
41           Drop connections by some criteria.  The $checker argument is a
42           subroutine that is called for each connection.  If the routine
43           returns a TRUE value then the connection is dropped.  The routine
44           is called with ($conn, $type, $key, $deposit_time) as arguments.
45
46           Shortcuts: If the $checker argument is absent (or "undef") all
47           cached connections are dropped.  If the $checker is a number then
48           all connections untouched that the given number of seconds or more
49           are dropped.  If $checker is a string then all connections of the
50           given type are dropped.
51
52           The $reason argument is passed on to the dropped() method.
53
54       $cache->prune
55           Calling this method will drop all connections that are dead.  This
56           is tested by calling the ping() method on the connections.  If the
57           ping() method exists and returns a FALSE value, then the connection
58           is dropped.
59
60       $cache->get_types
61           This returns all the 'type' fields used for the currently cached
62           connections.
63
64       $cache->get_connections( [$type] )
65           This returns all connection objects of the specified type.  If no
66           type is specified then all connections are returned.  In scalar
67           context the number of cached connections of the specified type is
68           returned.
69
70       The following methods are called by low-level protocol modules to try
71       to save away connections and to get them back.
72
73       $cache->deposit($type, $key, $conn)
74           This method adds a new connection to the cache.  As a result other
75           already cached connections might be dropped.  Multiple connections
76           with the same $type/$key might added.
77
78       $conn = $cache->withdraw($type, $key)
79           This method tries to fetch back a connection that was previously
80           deposited.  If no cached connection with the specified $type/$key
81           is found, then "undef" is returned.  There is not guarantee that a
82           deposited connection can be withdrawn, as the cache manger is free
83           to drop connections at any time.
84
85       The following methods are called internally.  Subclasses might want to
86       override them.
87
88       $conn->enforce_limits([$type])
89           This method is called with after a new connection is added
90           (deposited) in the cache or capacity limits are adjusted.  The
91           default implementation drops connections until the specified
92           capacity limits are not exceeded.
93
94       $conn->dropping($conn_record, $reason)
95           This method is called when a connection is dropped.  The record
96           belonging to the dropped connection is passed as the first argument
97           and a string describing the reason for the drop is passed as the
98           second argument.  The default implementation makes some noise if
99           the $LWP::ConnCache::DEBUG variable is set and nothing more.
100

SUBCLASSING

102       For specialized cache policy it makes sense to subclass
103       "LWP::ConnCache" and perhaps override the deposit(), enforce_limits()
104       and dropping() methods.
105
106       The object itself is a hash.  Keys prefixed with "cc_" are reserved for
107       the base class.
108

SEE ALSO

110       LWP::UserAgent
111
113       Copyright 2001 Gisle Aas.
114
115       This library is free software; you can redistribute it and/or modify it
116       under the same terms as Perl itself.
117
118
119
120perl v5.12.4                      2009-10-03                 LWP::ConnCache(3)
Impressum