1POE::Component::Client:U:sTeCrP(C3o)ntributed Perl DocumPeOnEt:a:tCioomnponent::Client::TCP(3)
2
6 POE::Component::Client::TCP - a simplified TCP client
7
9 #!perl
10 use warnings;
12 use strict;
13 use POE qw(Component::Client::TCP);
15 POE::Component::Client::TCP->new(
17 RemoteAddress => "yahoo.com",
18 RemotePort => 80,
19 Connected => sub {
20 $_[HEAP]{server}->put("HEAD /");
21 },
22 ServerInput => sub {
23 my $input = $_[ARG0];
24 print "from server: $input\n";
25 },
26 );
27 POE::Kernel->run();
29 exit;
30
32 POE::Component::Client::TCP implements a generic single-Session client.
33 Internally it uses POE::Wheel::SocketFactory to establish the
34 connection and POE::Wheel::ReadWrite to interact with the server.
35 POE::Component::Cilent::TCP is customized by providing callbacks for
37 common operations. Most operations have sensible default callbacks, so
38 clients may be created with as little work as possible.
39 Performance Considerations
41 POE::Component::Client::TCP's ease of use comes at a price. The
42 component is generic, so it's not tuned to perform well for any
43 particular application.
44 If performance is your primary goal, POE::Kernel's select_read() and
46 select_write() perform about the same as IO::Select, but your code will
47 be portable across every event loop POE supports.
48
50 new
51 new() starts a client based on POE::Component::Client::TCP and returns
52 the ID of the session that will handle server interaction.
53 new() returns immediately, which may be before the client has
55 established its connection. It is always reliable to wait for the
56 "Connected" callback to fire before transmitting data to the server.
57 The client's constructor may seem to take a daunting number of
59 parameters. As with most POE modules, POE::Component::Client::TCP
60 tries to do as much work in its constructor so that the run-time code
61 path is relatively light.
62 Constructor Parameters Affecting the Session
64 The parameters in this section affect how the client's POE::Session
66 object will be created.
67 Alias
69 "Alias" is an optional symbolic name for the client's Session. It
71 allows other sessions to post events to the client, such as "shutdown"
72 and "reconnect". The client itself may yield() these events, so an
73 alias isn't usually needed.
74 Alias => "client",
76 Args
78 "Args" is optional. When specified, it holds an ARRAYREF that will be
80 passed to the "Started" callback via @_[ARG0..$#_]. This allows a
81 program to pass extra information into the client session.
82 InlineStates
84 "InlineStates" is optional. If specified, it must hold a hashref of
86 named callbacks. Its syntax is that of POE:Session->create()'s
87 inline_states parameter.
88 ObjectStates
90 If "ObjectStates" is specified, it must holde an arrayref of objects
92 and the events they will handle. The arrayref must follow the syntax
93 for POE::Session->create()'s object_states parameter.
94 PackageStates
96 When the optional "PackageStates" is set, it must hold an arrayref of
98 package names and the events they will handle The arrayref must follow
99 the syntax for POE::Session->create()'s package_states parameter.
100 PreConnect
102 "PreConnect" is called before "Connected", and it has different
104 parameters: $_[ARG0] contains a copy of the socket before it's given to
105 POE::Wheel::ReadWrite for management. Most HEAP members are set,
106 except of course $_[HEAP]{server}, because the POE::Wheel::ReadWrite
107 object has not been created yet. "PreConnect" may enable SSL on the
108 socket using POE::Component::SSLify. "PreConnect" must return a valid
109 socket to complete the connection; the client will disconnect if
110 anything else is returned.
111 PreConnect => {
113 # Convert the socket into an SSL socket.
114 my $socket = eval { Client_SSLify($_[ARG0]) };
115 # Disconnect if SSL failed.
117 return if $@;
118 # Return the SSL-ified socket.
120 return $socket;
121 }
122 SessionType
124 Each client is created within its own Session. "SessionType" names the
126 class that will be used to create the session.
127 SessionType => "POE::Session::MultiDispatch",
129 "SessionType" is optional. The component will use "POE::Session" by
131 default.
132 SessionParams
134 "SessionParams" specifies additional parameters that will be passed to
136 the "SessionType" constructor at creation time. It must be an array
137 reference.
138 SessionParams => [ options => { debug => 1, trace => 1 } ],
140 Note: POE::Component::Client::TCP supplies its own POE::Session
142 constructor parameters. Conflicts between them and "SessionParams" may
143 cause the component to behave erratically. To avoid such problems,
144 please limit SessionParams to the "options" hash. See POE::Session for
145 an known options.
146 We may enable other options later. Please let us know if you need
148 something.
149 Started
151 "Started" sets an optional callback that will be invoked within the
153 client session has been started. The callback's parameters are the
154 usual for the session's _start handler.
155 "Args" may be used to pass additional parameters to "Started". This
157 can be used to bypass issues introduced by closures. The values from
158 "Args" will be included in the @_[ARG0..$#_] parameters.
159 sub handle_started {
161 my @args = @_[ARG0..$#_];
162 # ...
163 }
164 POE::Wheel::SocketFactory Constructor Parameters
166 The constructor parameters in this section affect how the client's
168 POE::Wheel::SocketFactory object will be created.
169 BindAddress
171 "BindAddress" specifies the local interface address to bind to before
173 starting to connect. This allows the client to connect from a specific
174 address when multiple interfaces are available.
175 "BindAddress" is optional. If specified, its value will be passed
177 directly to POE::Wheel::SocketFactory's BindAddress constructor
178 parameter.
179 BindPort
181 "BindPort" sets the local socket port that the client will be bound to
183 before starting to connect. This allows the client to connect from a
184 specific port.
185 It's not usually necessary to bind to a particular port, so "BindPort"
187 is optional and disabled by default.
188 If specified, the value in "BindPort" is passed directly to
190 POE::Wheel::SocketFactory's own BindPort constructor parameter.
191 ConnectError
193 "ConnectError" is an optional callback to handle errors from
195 POE::Wheel::SocketFactory. These errors happen when a socket can't be
196 created or has trouble connecting to the remote host.
197 The following parameters will be passed to the callback along with the
199 usual POE event parameters: $_[ARG0] will describe what was happening
200 at the time of failure. $_[ARG1] and $_[ARG2] will contain the numeric
201 and string versions of $!, respectively.
202 Depending on the nature of the error and the type of client, it may be
204 useful to reconnect from the ConnectError callback.
205 ConnectError => sub {
207 my ($operation, $error_number, $error_string) = @_[ARG0..ARG2];
208 warn "$operation error $error_number occurred: $error_string";
209 if (error_is_recoverable($error_number)) {
210 $_[KERNEL]->delay( reconnect => 60 );
211 }
212 else {
213 $_[KERNEL]->yield("shutdown");
214 }
215 },
216 POE::Component::Client::TCP will shut down after ConnectError if a
218 reconnect isn't requested.
219 Connected
221 Connections are asynchronously set up and may take some time to
223 complete. "Connected" is an optional callback that notifies a program
224 when the connection has finally been made.
225 This is an advisory callback that occurs after a POE::Wheel::ReadWrite
227 object has already been created. Programs should not need to create
228 their own.
229 "Connected" is called in response to POE::Wheel::SocketFactory's
231 SuccessEvent. In addition to the usual POE event parameters, it
232 includes a copy of the established socket handle in $_[ARG0].
233 POE::Component::Client::TCP will manage the socket, so an application
234 should rarely need to save a copy of it. $_[ARG1] and $_[ARG2] contain
235 the remote address and port as returned from getpeername().
236 Connected => {
238 my ($socket, $peer_addr, $peer_port) = @_[ARG0, ARG1, ARG2];
239 # ...
240 }
241 See "PreConnect" to modify the socket before it's given to
243 POE::Wheel::ReadWrite.
244 ConnectTimeout
246 "ConnectTimeout" is the maximum number of seconds to wait for a
248 connection to be established. If it is omitted, Client::TCP relies on
249 the operating system to abort stalled connect() calls.
250 The application will be notified of a timeout via the ConnectError
252 callback. In the case of a timeout, $_[ARG0] will contain "connect",
253 and $_[ARG1] and $_[ARG2] will contain the numeric and string
254 representations of the ETIMEDOUT error.
255 Domain
257 "Domain" sets the address or protocol family within which to operate.
259 The "Domain" may be any value that POE::Wheel::SocketFactory supports.
260 AF_INET (Internet address space) is used by default.
261 Use AF_INET6 for IPv6 support. This constant is exported by Socket6,
263 which must be loaded before POE::Component::Client::TCP.
264 RemoteAddress
266 "RemoteAddress" contains the address of the server to connect to. It
268 is required and may contain a host name ("poe.perl.org"), a dot- or
269 colon-separated numeric address (depending on the Domain), or a packed
270 socket address. Pretty much anything POE::Wheel::SocketFactory's
271 RemoteAddress parameter does.
272 RemotePort
274 "RemotePort" contains the port of the server to connect to. It is
276 required and may be a service name ("echo") or number (7).
277 POE::Wheel::ReadWrite Constructor Parameters
279 Parameters in this section control configuration of the client's
281 POE::Wheel::ReadWrite object.
282 Disconnected
284 "Disconnected" is an optional callback to notify a program that an
286 established socket has been disconnected. It includes no special
287 parameters.
288 It may be useful to reconnect from the Disconnected callback, in the
290 case of MUD bots or long-running services. For example:
291 Disconnected => sub {
293 $_[KERNEL]->delay( reconnect => 60 );
294 },
295 The component will shut down if the connection ceases without being
297 reconnected.
298 Filter
300 "Filter" specifies the type of POE::Filter object that will parse input
302 from and serialize output to a server. It may either be a scalar, an
303 array reference, or a POE::Filter object.
304 If "Filter" is a scalar, it will be expected to contain a POE::Filter
306 class name:
307 Filter => "POE::Filter::Line",
309 "Filter" is optional. In most cases, the default "POE::Filter::Line"
311 is fine.
312 If "Filter" is an array reference, the first item in the array will be
314 treated as a POE::Filter class name. The remaining items will be
315 passed to the filter's constructor. In this example, the vertical bar
316 will be used as POE::Filter::Line's record terminator:
317 Filter => [ "POE::Filter::Line", Literal => "|" ],
319 If it is an object, it will be cloned every time the client connects:
321 Filter => POE::Filter::Line->new(Literal => "|"),
323 Be sure to "use" the appropriate POE::Filter subclass when specifying a
325 "Filter" other than the default.
326 ServerError
328 "ServerError" is an optional callback that will be invoked when an
330 established server connection has encountered some kind of error. It
331 is triggered by POE::Wheel::ReadWrite's ErrorEvent. By default, the
332 component will log any errors to STDERR. This may be suppressed by
333 defining a quieter ServerError callback.
334 As with "ConnectError", it is invoked with the customary error
336 parameters: $_[ARG0] will contain the name of the operation that
337 failed. $_[ARG1] and $_[ARG2] will hold the numeric and string forms
338 of $!, respectively.
339 Components usually disconnect on error. POE::Component::Client::TCP
341 will shut down if the socket disconnects without being reconnected.
342 ServerFlushed
344 "ServerFlushed" is an optional callback to notify a program that
346 ReadWrite's output buffers have completely flushed. It has no special
347 parameters.
348 The component will shut down after a server flush if $heap->{shutdown}
350 is set.
351 ServerInput
353 "ServerInput" is a required callback. It is called for each fully
355 parsed input record received by POE::Wheel::ReadWrite. $_[ARG0]
356 contains the input record, the format of which is determined by the
357 "Filter" constructor parameter.
358 "SeverInput" will stop being called when $_[HEAP]{shutdown} is true.
360 The most reliable way to set the "shutdown" member is to call
361 $_[KERNEL]->yield("shutdown").
362
364 POE::Component::Client::TCP handles a small number of public "command"
365 messages. These may be posted into the client from an external
366 session, or yielded from within the client.
367 connect
369 The "connect" event causes POE::Component::Client::TCP to begin
370 connecting to a server. It optionally includes a new RemoteHost and
371 RemotePort, both of which will be used for subsequent reconnections.
372 $_[KERNEL]->post(alias => connect => "127.0.0.1", 80);
374 If the client is already connected to a server, it will disconnect
376 immediately before beginning the new connection procedure. Buffered
377 input and output will be lost.
378 reconnect
380 The "reconnect" command causes POE::Component::Client::TCP to
381 immediately disconnect its current connection and begin reconnecting to
382 its most recently set RemoteHost and RemotePort. Any buffered input
383 and output will be lost.
384 shutdown
386 The "shutdown" command tells POE::Component::Client::TCP to flush its
387 buffers, disconnect, and begin DESTROY procedures.
388 All input will be discarded after receipt of "shutdown". All pending
390 output will be written to the server socket before disconnecting and
391 destructing.
392
394 POE::Component::Client::TCP requires some heap space for its own
395 bookkeeping. The following members are used and should be used as
396 directed, or with care.
397 This sample input handler is an example of most reserved heap members:
399 sub handle_input {
401 # Pending input from when we were connected.
402 return unless $_[HEAP]{connected};
403 # We've been shut down.
405 return if $_[HEAP]{shutdown};
406 my $input = $_[ARG0];
408 $_[HEAP]{server}->put("you sent: $input");
409 }
410 server
412 The read-only "server" heap member contains the POE::Wheel object used
413 to connect to or talk with the server. While the component is
414 connecting, "server" will be a POE::Wheel::SocketFactory object. After
415 the connection has been made, "server" is replaced with a
416 POE::Wheel::ReadWrite object.
417 The most reliable way to avoid prematurely using "server" is to first
419 check the "connected" reserved heap member. See the example above.
420 shutdown
422 "shutdown" is a read-only flag that tells the component it's shutting
423 down. It should only be by the "shutdown" event, which does other
424 cleanup.
425 "shutdown" may be checked to avoid starting new work during a client's
427 shutting-down procedure. See the example above.
428 connected
430 "connected" is a read-only flag that indicates whether the component is
431 currently connected.
432 shutdown_on_error
434 "shutdown_on_error" is a read-only flag that governs the component's
435 shutdown-on-error behavior. When true, POE::Component::Client::TCP
436 will automatically shutdown when it encounters an error.
437
439 The SEE ALSO section in POE contains a table of contents covering the
440 entire POE distribution.
441 POE::Component::Server::TCP is the server-side counterpart to this
443 module.
444 This component uses and exposes features from POE::Filter,
446 POE::Wheel::SocketFactory, and POE::Wheel::ReadWrite.
447 See "SYNOPSIS" in POE::Wheel::SocketFactory for a more efficient but
449 lower-level way to create clients and servers.
450
452 This looks nothing like what Ann envisioned.
453 POE::Component::Client::TCP is a generic client. As such, it's not
455 tuned for any particular task. While it handles the common cases well
456 and with a minimum of code, it may not be suitable for everything.
457
459 POE::Component::Client::TCP is Copyright 2001-2009 by Rocco Caputo.
460 All rights are reserved. POE::Component::Client::TCP is free software,
461 and it may be redistributed and/or modified under the same terms as
462 Perl itself.
463 POE::Component::Client::TCP is based on code, used with permission,
465 from Ann Barcomb <kudra@domaintje.com>.
466 POE::Component::Client::TCP is based on code, used with permission,
468 from Jos Boumans <kane@cpan.org>.
469perl v5.12.1 2010-04-03 POE::Component::Client::TCP(3)