Edit File: LWP::ConnCache.3pm
.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "LWP::ConnCache 3" .TH LWP::ConnCache 3 "2015-02-14" "perl v5.10.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" LWP::ConnCache \- Connection cache manager .SH "NOTE" .IX Header "NOTE" This module is experimental. Details of its interface is likely to change in the future. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& use LWP::ConnCache; \& my $cache = LWP::ConnCache\->new; \& $cache\->deposit($type, $key, $sock); \& $sock = $cache\->withdraw($type, $key); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`LWP::ConnCache\*(C'\fR class is the standard connection cache manager for LWP::UserAgent. .PP The following basic methods are provided: .ie n .IP "$cache = LWP::ConnCache\->new( %options )" 4 .el .IP "\f(CW$cache\fR = LWP::ConnCache\->new( \f(CW%options\fR )" 4 .IX Item "$cache = LWP::ConnCache->new( %options )" This method constructs a new \f(CW\*(C`LWP::ConnCache\*(C'\fR object. The only option currently accepted is 'total_capacity'. If specified it initialize the total_capacity option. It defaults to the value 1. .ie n .IP "$cache\->total_capacity( [$num_connections] )" 4 .el .IP "\f(CW$cache\fR\->total_capacity( [$num_connections] )" 4 .IX Item "$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 \f(CW0\fR, then all connections are immediately dropped. If set to \f(CW\*(C`undef\*(C'\fR, then there is no limit. .ie n .IP "$cache\->capacity($type, [$num_connections] )" 4 .el .IP "\f(CW$cache\fR\->capacity($type, [$num_connections] )" 4 .IX Item "$cache->capacity($type, [$num_connections] )" Get/set a limit for the number of connections of the specified type that can be cached. The \f(CW$type\fR will typically be a short string like \&\*(L"http\*(R" or \*(L"ftp\*(R". .ie n .IP "$cache\->drop( [$checker, [$reason]] )" 4 .el .IP "\f(CW$cache\fR\->drop( [$checker, [$reason]] )" 4 .IX Item "$cache->drop( [$checker, [$reason]] )" Drop connections by some criteria. The \f(CW$checker\fR argument is a subroutine that is called for each connection. If the routine returns a \s-1TRUE\s0 value then the connection is dropped. The routine is called with ($conn, \f(CW$type\fR, \f(CW$key\fR, \f(CW$deposit_time\fR) as arguments. .Sp Shortcuts: If the \f(CW$checker\fR argument is absent (or \f(CW\*(C`undef\*(C'\fR) all cached connections are dropped. If the \f(CW$checker\fR is a number then all connections untouched that the given number of seconds or more are dropped. If \f(CW$checker\fR is a string then all connections of the given type are dropped. .Sp The \f(CW$reason\fR argument is passed on to the \fIdropped()\fR method. .ie n .IP "$cache\->prune" 4 .el .IP "\f(CW$cache\fR\->prune" 4 .IX Item "$cache->prune" Calling this method will drop all connections that are dead. This is tested by calling the \fIping()\fR method on the connections. If the \fIping()\fR method exists and returns a \s-1FALSE\s0 value, then the connection is dropped. .ie n .IP "$cache\->get_types" 4 .el .IP "\f(CW$cache\fR\->get_types" 4 .IX Item "$cache->get_types" This returns all the 'type' fields used for the currently cached connections. .ie n .IP "$cache\->get_connections( [$type] )" 4 .el .IP "\f(CW$cache\fR\->get_connections( [$type] )" 4 .IX Item "$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. .PP The following methods are called by low-level protocol modules to try to save away connections and to get them back. .ie n .IP "$cache\->deposit($type, $key, $conn)" 4 .el .IP "\f(CW$cache\fR\->deposit($type, \f(CW$key\fR, \f(CW$conn\fR)" 4 .IX Item "$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 \f(CW$type\fR/$key might added. .ie n .IP "$conn = $cache\->withdraw($type, $key)" 4 .el .IP "\f(CW$conn\fR = \f(CW$cache\fR\->withdraw($type, \f(CW$key\fR)" 4 .IX Item "$conn = $cache->withdraw($type, $key)" This method tries to fetch back a connection that was previously deposited. If no cached connection with the specified \f(CW$type\fR/$key is found, then \f(CW\*(C`undef\*(C'\fR 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. .PP The following methods are called internally. Subclasses might want to override them. .ie n .IP "$conn\->enforce_limits([$type])" 4 .el .IP "\f(CW$conn\fR\->enforce_limits([$type])" 4 .IX Item "$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. .ie n .IP "$conn\->dropping($conn_record, $reason)" 4 .el .IP "\f(CW$conn\fR\->dropping($conn_record, \f(CW$reason\fR)" 4 .IX Item "$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 \&\f(CW$LWP::ConnCache::DEBUG\fR variable is set and nothing more. .SH "SUBCLASSING" .IX Header "SUBCLASSING" For specialized cache policy it makes sense to subclass \&\f(CW\*(C`LWP::ConnCache\*(C'\fR and perhaps override the \fIdeposit()\fR, \fIenforce_limits()\fR and \fIdropping()\fR methods. .PP The object itself is a hash. Keys prefixed with \f(CW\*(C`cc_\*(C'\fR are reserved for the base class. .SH "SEE ALSO" .IX Header "SEE ALSO" LWP::UserAgent .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2001 Gisle Aas. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Back to File Manager