1POE::Component::Client:U:sKeerepCaolnitvrei(b3u)ted PerlPODEo:c:uCmoemnptoanteinotn::Client::Keepalive(3)
2
6 POE::Component::Client::Keepalive - manage connections, with keep-alive
7
9 version 0.272
10
12 use warnings;
13 use strict;
14 use POE;
16 use POE::Component::Client::Keepalive;
17 POE::Session->create(
19 inline_states => {
20 _start => \&start,
21 got_conn => \&got_conn,
22 got_error => \&handle_error,
23 got_input => \&handle_input,
24 }
25 );
26 POE::Kernel->run();
28 exit;
29 sub start {
31 $_[HEAP]{ka} = POE::Component::Client::Keepalive->new();
32 $_[HEAP]{ka}->allocate(
34 scheme => "http",
35 addr => "127.0.0.1",
36 port => 9999,
37 event => "got_conn",
38 context => "arbitrary data (even a reference) here",
39 timeout => 60,
40 );
41 print "Connection is in progress.\n";
43 }
44 sub got_conn {
46 my ($kernel, $heap, $response) = @_[KERNEL, HEAP, ARG0];
47 my $conn = $response->{connection};
49 my $context = $response->{context};
50 if (defined $conn) {
52 if ($response->{from_cache}) {
53 print "Connection was established immediately.\n";
54 }
55 else {
56 print "Connection was established asynchronously.\n";
57 }
58 $conn->start(
60 InputEvent => "got_input",
61 ErrorEvent => "got_error",
62 );
63 return;
64 }
65 print(
67 "Connection could not be established: ",
68 "$response->{function} error $response->{error_num}: ",
69 "$response->{error_str}\n"
70 );
71 }
72 sub handle_input {
74 my $input = $_[ARG0];
75 print "$input\n";
76 }
77 sub handle_error {
79 my $heap = $_[HEAP];
80 delete $heap->{connection};
81 $heap->{ka}->shutdown();
82 }
83
85 POE::Component::Client::Keepalive creates and manages connections for
86 other components. It maintains a cache of kept-alive connections for
87 quick reuse. It is written specifically for clients that can benefit
88 from kept-alive connections, such as HTTP clients. Using it for one-
89 shot connections would probably be silly.
90 new
92 Creates a new keepalive connection manager. A program may contain
93 several connection managers. Each will operate independently of the
94 others. None will know about the limits set in the others, so it's
95 possible to overrun your file descriptors for a process if you're not
96 careful.
97 new() takes up to five parameters. All of them are optional.
99 To limit the number of simultaneous connections to a particular host
101 (defined by a combination of scheme, address and port):
102 max_per_host => $max_simultaneous_host_connections, # defaults to 4
104 To limit the overall number of connections that may be open at once,
106 use
107 max_open => $maximum_open_connections, # defaults to 128
109 Programs are required to give connections back to the manager when
111 they are done. See the free() method for how that works. The
112 connection manager will keep connections alive for a period of time
113 before recycling them. The maximum keep-alive time may be set with
114 keep_alive => $seconds_to_keep_free_conns_alive, # defaults to 15
116 Programs may not want to wait a long time for a connection to be
118 established. They can set the request timeout to alter how long the
119 component holds a request before generating an error.
120 timeout => $seconds_to_process_a_request, # defaults to 120
122 Specify a bind_address to bind all client sockets to a particular
124 local address. The value of bind_address will be passed directly to
125 POE::Wheel::SocketFactory. See that module's documentation for
126 implementation details.
127 allocate
129 Allocate a new connection. Allocate() will return a request ID
130 immediately. The allocated connection, however, will be posted back
131 to the requesting session. This happens even if the connection was
132 found in the component's keep-alive cache. It's a bit slower, but
133 the use cases are cleaner that way.
134 Allocate() requires five parameters and has an optional sixth.
136 Specify the scheme that will be used to communicate on the connection
138 (typically http or https). The scheme is required, but you're free
139 to make something up here. It's used internally to differentiate
140 different types of socket (e.g., ssl vs. cleartext) on the same
141 address and port.
142 scheme => $connection_scheme,
144 Request a connection to a particular address and port. The address
146 and port must be numeric. Both the address and port are required.
147 address => $remote_address,
149 port => $remote_port,
150 Specify an name of the event to post when an asynchronous response is
152 ready. This is of course required.
153 event => $return_event,
155 Set the connection timeout, in seconds. The connection manager will
157 post back an error message if it can't establish a connection within
158 the requested time. This parameter is optional. It will default to
159 the master timeout provided to the connection manager's constructor.
160 timeout => $connect_timeout,
162 Specify additional contextual data. The context defines the
164 connection's purpose. It is used to maintain continuity between a
165 call to allocate() and an asynchronous response. A context is
166 extremely handy, but it's optional.
167 context => $context_data,
169 In summary:
171 $mgr->allocate(
173 scheme => "http",
174 address => "127.0.0.1",
175 port => 80,
176 event => "got_a_connection",
177 context => \%connection_context,
178 );
179 The response event ("got_a_connection" in this example) contains
181 several fields, passed as a list of key/value pairs. The list may be
182 assigned to a hash for convenience:
183 sub got_a_connection {
185 my %response = @_[ARG0..$#_];
186 ...;
187 }
188 Four of the fields exist to echo back your data:
190 $response{address} = $your_request_address;
192 $response{context} = $your_request_context;
193 $response{port} = $your_request_port;
194 $response{scheme} = $your_request_scheme;
195 One field returns the connection object if the connection was
197 successful, or undef if there was a failure:
198 $response{connection} = $new_socket_handle;
200 On success, another field tells you whether the connection contains
202 all new materials. That is, whether the connection has been recycled
203 from the component's cache or created anew.
204 $response{from_cache} = $status;
206 The from_cache status may be "immediate" if the connection was
208 immediately available from the cache. It will be "deferred" if the
209 connection was reused, but another user had to release it first.
210 Finally, from_cache will be false if the connection had to be created
211 to satisfy allocate().
212 Three other fields return error information if the connection failed.
214 They are not present if the connection was successful.
215 $response{function} = $name_of_failing_function;
217 $response{error_num} = $! as a number;
218 $response{error_str} = $! as a string;
219 free
221 Free() notifies the connection manager when connections are free to
222 be reused. Freed connections are entered into the keep-alive pool
223 and may be returned by subsequent allocate() calls.
224 $mgr->free($socket);
226 For now free() is called with a socket, not a connection object.
228 This is usually not a problem since
229 POE::Component::Connection::Keepalive objects call free() for you
230 when they are destroyed.
231 Not calling free() will cause a program to leak connections. This is
233 also not generally a problem, since free() is called automatically
234 whenever connection objects are destroyed.
235 deallocate
237 Cancel a connection that has not yet been established. Requires one
238 parameter, the request ID returned by allocate().
239 shutdown
241 The keep-alive pool requires connections to be active internally.
242 This may keep a program active even when all connections are idle.
243 The shutdown() method forces the connection manager to clear its
244 keep-alive pool, allowing a program to terminate gracefully.
245 $mgr->shutdown();
247
249 POE POE::Component::Connection::Keepalive
250
252 This distribution is copyright 2004-2009 by Rocco Caputo. All rights
253 are reserved. This distribution is free software; you may redistribute
254 it and/or modify it under the same terms as Perl itself.
255
257 Rocco Caputo <rcaputo@cpan.org>
258
260 Rob Bloodgood helped out a lot. Thank you.
261 Joel Bernstein solved some nasty race conditions. Portugal Telecom
263 <http://www.sapo.pt/> was kind enough to support his contributions.
264
266 https://rt.cpan.org/Dist/Display.html?Queue=POE-Component-Client-Keepalive
267
269 http://gitorious.org/poe-component-client-keepalive
270 http://github.com/rcaputo/poe-component-client-keepalive
271
273 http://search.cpan.org/dist/POE-Component-Client-Keepalive/
274perl v5.28.1 2014-07-0P8OE::Component::Client::Keepalive(3)