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

METHODS

23       The following basic methods are provided:
24
25   new
26           my $cache = LWP::ConnCache->new( %options )
27
28       This method constructs a new LWP::ConnCache object.  The only option
29       currently accepted is "total_capacity".  If specified it initializes
30       the "total_capacity" in LWP::ConnCache option. It defaults to 1.
31
32   total_capacity
33           my $cap = $cache->total_capacity;
34           $cache->total_capacity(0); # drop all immediately
35           $cache->total_capacity(undef); # no limit
36           $cache->total_capacity($number);
37
38       Get/sets the number of connection that will be cached.  Connections
39       will start to be dropped when this limit is reached.  If set to 0, then
40       all connections are immediately dropped.  If set to "undef", then there
41       is no limit.
42
43   capacity
44           my $http_capacity = $cache->capacity('http');
45           $cache->capacity('http', 2 );
46
47       Get/set a limit for the number of connections of the specified type
48       that can be cached.  The first parameter is a short string like "http"
49       or "ftp".
50
51   drop
52           $cache->drop(); # Drop ALL connections
53           # which is just a synonym for:
54           $cache->drop(sub{1}); # Drop ALL connections
55           # drop all connections older than 22 seconds and add a reason for it!
56           $cache->drop(22, "Older than 22 secs dropped");
57           # which is just a synonym for:
58           $cache->drop(sub {
59               my ($conn, $type, $key, $deposit_time) = @_;
60               if ($deposit_time < 22) {
61                   # true values drop the connection
62                   return 1;
63               }
64               # false values don't drop the connection
65               return 0;
66           }, "Older than 22 secs dropped" );
67
68       Drop connections by some criteria.  The $checker argument is a
69       subroutine that is called for each connection.  If the routine returns
70       a TRUE value then the connection is dropped.  The routine is called
71       with "($conn, $type, $key, $deposit_time)" as arguments.
72
73       Shortcuts: If the $checker argument is absent (or "undef") all cached
74       connections are dropped.  If the $checker is a number then all
75       connections untouched that the given number of seconds or more are
76       dropped.  If $checker is a string then all connections of the given
77       type are dropped.
78
79       The "reason" is passed on to the "dropped" in LWP::ConnCache method.
80
81   prune
82           $cache->prune();
83
84       Calling this method will drop all connections that are dead.  This is
85       tested by calling the "ping" in LWP::ConnCache method on the
86       connections. If the "ping" in LWP::ConnCache method exists and returns
87       a false value, then the connection is dropped.
88
89   get_types
90           my @types = $cache->get_types();
91
92       This returns all the "type" fields used for the currently cached
93       connections.
94
95   get_connections
96           my @conns = $cache->get_connections(); # all connections
97           my @conns = $cache->get_connections('http'); # connections for http
98
99       This returns all connection objects of the specified type.  If no type
100       is specified then all connections are returned.  In scalar context the
101       number of cached connections of the specified type is returned.
102

PROTOCOL METHODS

104       The following methods are called by low-level protocol modules to try
105       to save away connections and to get them back.
106
107   deposit
108           $cache->deposit($type, $key, $conn);
109
110       This method adds a new connection to the cache.  As a result, other
111       already cached connections might be dropped.  Multiple connections with
112       the same type/key might be added.
113
114   withdraw
115           my $conn = $cache->withdraw($type, $key);
116
117       This method tries to fetch back a connection that was previously
118       deposited.  If no cached connection with the specified $type/$key is
119       found, then "undef" is returned.  There is not guarantee that a
120       deposited connection can be withdrawn, as the cache manger is free to
121       drop connections at any time.
122

INTERNAL METHODS

124       The following methods are called internally.  Subclasses might want to
125       override them.
126
127   enforce_limits
128           $conn->enforce_limits([$type])
129
130       This method is called with after a new connection is added (deposited)
131       in the cache or capacity limits are adjusted.  The default
132       implementation drops connections until the specified capacity limits
133       are not exceeded.
134
135   dropping
136           $conn->dropping($conn_record, $reason)
137
138       This method is called when a connection is dropped.  The record
139       belonging to the dropped connection is passed as the first argument and
140       a string describing the reason for the drop is passed as the second
141       argument.  The default implementation makes some noise if the
142       $LWP::ConnCache::DEBUG variable is set and nothing more.
143

SUBCLASSING

145       For specialized cache policy it makes sense to subclass
146       "LWP::ConnCache" and perhaps override the "deposit" in LWP::ConnCache,
147       "enforce_limits" in LWP::ConnCache, and "dropping" in LWP::ConnCache
148       methods.
149
150       The object itself is a hash.  Keys prefixed with "cc_" are reserved for
151       the base class.
152

SEE ALSO

154       LWP::UserAgent
155
157       Copyright 2001 Gisle Aas.
158
159       This library is free software; you can redistribute it and/or modify it
160       under the same terms as Perl itself.
161
162
163
164perl v5.36.0                      2023-03-01                 LWP::ConnCache(3)
Impressum