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