1POE::Component::Client:U:sKeerepCaolnitvrei(b3u)ted PerlPODEo:c:uCmoemnptoanteinotn::Client::Keepalive(3)
2
3
4

NAME

6       POE::Component::Client::Keepalive - manage connections, with keep-alive
7

VERSION

9       version 0.272
10

SYNOPSIS

12         use warnings;
13         use strict;
14
15         use POE;
16         use POE::Component::Client::Keepalive;
17
18         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
27         POE::Kernel->run();
28         exit;
29
30         sub start {
31           $_[HEAP]{ka} = POE::Component::Client::Keepalive->new();
32
33           $_[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
42           print "Connection is in progress.\n";
43         }
44
45         sub got_conn {
46           my ($kernel, $heap, $response) = @_[KERNEL, HEAP, ARG0];
47
48           my $conn    = $response->{connection};
49           my $context = $response->{context};
50
51           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
59             $conn->start(
60               InputEvent => "got_input",
61               ErrorEvent => "got_error",
62             );
63             return;
64           }
65
66           print(
67             "Connection could not be established: ",
68             "$response->{function} error $response->{error_num}: ",
69             "$response->{error_str}\n"
70           );
71         }
72
73         sub handle_input {
74           my $input = $_[ARG0];
75           print "$input\n";
76         }
77
78         sub handle_error {
79           my $heap = $_[HEAP];
80           delete $heap->{connection};
81           $heap->{ka}->shutdown();
82         }
83

DESCRIPTION

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
91       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
98         new() takes up to five parameters.  All of them are optional.
99
100         To limit the number of simultaneous connections to a particular host
101         (defined by a combination of scheme, address and port):
102
103           max_per_host => $max_simultaneous_host_connections, # defaults to 4
104
105         To limit the overall number of connections that may be open at once,
106         use
107
108           max_open     => $maximum_open_connections, # defaults to 128
109
110         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
115           keep_alive   => $seconds_to_keep_free_conns_alive, # defaults to 15
116
117         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
121           timeout      => $seconds_to_process_a_request, # defaults to 120
122
123         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
128       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
135         Allocate() requires five parameters and has an optional sixth.
136
137         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
143           scheme  => $connection_scheme,
144
145         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
148           address => $remote_address,
149           port    => $remote_port,
150
151         Specify an name of the event to post when an asynchronous response is
152         ready.  This is of course required.
153
154           event   => $return_event,
155
156         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
161           timeout => $connect_timeout,
162
163         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
168           context => $context_data,
169
170         In summary:
171
172           $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
180         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
184           sub got_a_connection {
185             my %response = @_[ARG0..$#_];
186             ...;
187           }
188
189         Four of the fields exist to echo back your data:
190
191           $response{address}    = $your_request_address;
192           $response{context}    = $your_request_context;
193           $response{port}       = $your_request_port;
194           $response{scheme}     = $your_request_scheme;
195
196         One field returns the connection object if the connection was
197         successful, or undef if there was a failure:
198
199           $response{connection} = $new_socket_handle;
200
201         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
205           $response{from_cache} = $status;
206
207         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
213         Three other fields return error information if the connection failed.
214         They are not present if the connection was successful.
215
216           $response{function}   = $name_of_failing_function;
217           $response{error_num}  = $! as a number;
218           $response{error_str}  = $! as a string;
219
220       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
225           $mgr->free($socket);
226
227         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
232         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
236       deallocate
237         Cancel a connection that has not yet been established.  Requires one
238         parameter, the request ID returned by allocate().
239
240       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
246           $mgr->shutdown();
247

SEE ALSO

249       POE POE::Component::Connection::Keepalive
250

LICENSE

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

AUTHOR

257       Rocco Caputo <rcaputo@cpan.org>
258

CONTRIBUTORS

260       Rob Bloodgood helped out a lot.  Thank you.
261
262       Joel Bernstein solved some nasty race conditions.  Portugal Telecom
263       <http://www.sapo.pt/> was kind enough to support his contributions.
264

BUG TRACKER

266       https://rt.cpan.org/Dist/Display.html?Queue=POE-Component-Client-Keepalive
267

REPOSITORY

269       http://gitorious.org/poe-component-client-keepalive
270       http://github.com/rcaputo/poe-component-client-keepalive
271

OTHER RESOURCES

273       http://search.cpan.org/dist/POE-Component-Client-Keepalive/
274
275
276
277perl v5.28.1                      2014-07-0P8OE::Component::Client::Keepalive(3)
Impressum