1LWP::ConnCache(3) User Contributed Perl Documentation LWP::ConnCache(3)
2
6 LWP::ConnCache - Connection cache manager
7
9 This module is experimental. Details of its interface is likely to
10 change in the future.
11
13 use LWP::ConnCache;
14 my $cache = LWP::ConnCache->new;
15 $cache->deposit($type, $key, $sock);
16 $sock = $cache->withdraw($type, $key);
17
19 The "LWP::ConnCache" class is the standard connection cache manager for
20 LWP::UserAgent.
21 The following basic methods are provided:
23 $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 $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 $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 $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 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 The $reason argument is passed on to the dropped() method.
53 $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 $cache->get_types
61 This returns all the 'type' fields used for the currently cached
62 connections.
63 $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 The following methods are called by low-level protocol modules to try
71 to save away connections and to get them back.
72 $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 $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 The following methods are called internally. Subclasses might want to
86 override them.
87 $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 $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
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 The object itself is a hash. Keys prefixed with "cc_" are reserved for
107 the base class.
108
110 LWP::UserAgent
111
113 Copyright 2001 Gisle Aas.
114 This library is free software; you can redistribute it and/or modify it
116 under the same terms as Perl itself.
117perl v5.12.4 2009-10-03 LWP::ConnCache(3)