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::Client::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 hold an arrayref of objects and
92 the events they will handle. The arrayref must follow the syntax for
93 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 Socket.
263 Also be sure to have Socket::GetAddrInfo installed, which is required
264 by POE::Wheel::SocketFactory for IPv6 support.
265 RemoteAddress
267 "RemoteAddress" contains the address of the server to connect to. It
269 is required and may contain a host name ("poe.perl.org"), a dot- or
270 colon-separated numeric address (depending on the Domain), or a packed
271 socket address. Pretty much anything POE::Wheel::SocketFactory's
272 RemoteAddress parameter does.
273 RemotePort
275 "RemotePort" contains the port of the server to connect to. It is
277 required and may be a service name ("echo") or number (7).
278 POE::Wheel::ReadWrite Constructor Parameters
280 Parameters in this section control configuration of the client's
282 POE::Wheel::ReadWrite object.
283 Disconnected
285 "Disconnected" is an optional callback to notify a program that an
287 established socket has been disconnected. It includes no special
288 parameters.
289 It may be useful to reconnect from the Disconnected callback, in the
291 case of MUD bots or long-running services. For example:
292 Disconnected => sub {
294 $_[KERNEL]->delay( reconnect => 60 );
295 },
296 The component will shut down if the connection ceases without being
298 reconnected.
299 Filter
301 "Filter" specifies the type of POE::Filter object that will parse input
303 from and serialize output to a server. It may either be a scalar, an
304 array reference, or a POE::Filter object.
305 If "Filter" is a scalar, it will be expected to contain a POE::Filter
307 class name:
308 Filter => "POE::Filter::Line",
310 "Filter" is optional. In most cases, the default "POE::Filter::Line"
312 is fine.
313 If "Filter" is an array reference, the first item in the array will be
315 treated as a POE::Filter class name. The remaining items will be
316 passed to the filter's constructor. In this example, the vertical bar
317 will be used as POE::Filter::Line's record terminator:
318 Filter => [ "POE::Filter::Line", Literal => "|" ],
320 If it is an object, it will be cloned every time the client connects:
322 Filter => POE::Filter::Line->new(Literal => "|"),
324 Be sure to "use" the appropriate POE::Filter subclass when specifying a
326 "Filter" other than the default.
327 ServerError
329 "ServerError" is an optional callback that will be invoked when an
331 established server connection has encountered some kind of error. It
332 is triggered by POE::Wheel::ReadWrite's ErrorEvent. By default, the
333 component will log any errors to STDERR. This may be suppressed by
334 defining a quieter ServerError callback.
335 As with "ConnectError", it is invoked with the customary error
337 parameters: $_[ARG0] will contain the name of the operation that
338 failed. $_[ARG1] and $_[ARG2] will hold the numeric and string forms
339 of $!, respectively.
340 Components usually disconnect on error. POE::Component::Client::TCP
342 will shut down if the socket disconnects without being reconnected.
343 ServerFlushed
345 "ServerFlushed" is an optional callback to notify a program that
347 ReadWrite's output buffers have completely flushed. It has no special
348 parameters.
349 The component will shut down after a server flush if $heap->{shutdown}
351 is set.
352 ServerInput
354 "ServerInput" is a required callback. It is called for each fully
356 parsed input record received by POE::Wheel::ReadWrite. $_[ARG0]
357 contains the input record, the format of which is determined by the
358 "Filter" constructor parameter.
359 "SeverInput" will stop being called when $_[HEAP]{shutdown} is true.
361 The most reliable way to set the "shutdown" member is to call
362 $_[KERNEL]->yield("shutdown").
363
365 POE::Component::Client::TCP handles a small number of public "command"
366 messages. These may be posted into the client from an external
367 session, or yielded from within the client.
368 connect
370 The "connect" event causes POE::Component::Client::TCP to begin
371 connecting to a server. It optionally includes a new RemoteHost and
372 RemotePort, both of which will be used for subsequent reconnections.
373 $_[KERNEL]->post(alias => connect => "127.0.0.1", 80);
375 If the client is already connected to a server, it will disconnect
377 immediately before beginning the new connection procedure. Buffered
378 input and output will be lost.
379 reconnect
381 The "reconnect" command causes POE::Component::Client::TCP to
382 immediately disconnect its current connection and begin reconnecting to
383 its most recently set RemoteHost and RemotePort. Any buffered input
384 and output will be lost.
385 shutdown
387 The "shutdown" command tells POE::Component::Client::TCP to flush its
388 buffers, disconnect, and begin DESTROY procedures.
389 All input will be discarded after receipt of "shutdown". All pending
391 output will be written to the server socket before disconnecting and
392 destructing.
393
395 POE::Component::Client::TCP requires some heap space for its own
396 bookkeeping. The following members are used and should be used as
397 directed, or with care.
398 This sample input handler is an example of most reserved heap members:
400 sub handle_input {
402 # Pending input from when we were connected.
403 return unless $_[HEAP]{connected};
404 # We've been shut down.
406 return if $_[HEAP]{shutdown};
407 my $input = $_[ARG0];
409 $_[HEAP]{server}->put("you sent: $input");
410 }
411 server
413 The read-only "server" heap member contains the POE::Wheel object used
414 to connect to or talk with the server. While the component is
415 connecting, "server" will be a POE::Wheel::SocketFactory object. After
416 the connection has been made, "server" is replaced with a
417 POE::Wheel::ReadWrite object.
418 The most reliable way to avoid prematurely using "server" is to first
420 check the "connected" reserved heap member. See the example above.
421 shutdown
423 "shutdown" is a read-only flag that tells the component it's shutting
424 down. It should only be by the "shutdown" event, which does other
425 cleanup.
426 "shutdown" may be checked to avoid starting new work during a client's
428 shutting-down procedure. See the example above.
429 connected
431 "connected" is a read-only flag that indicates whether the component is
432 currently connected.
433 shutdown_on_error
435 "shutdown_on_error" is a read-only flag that governs the component's
436 shutdown-on-error behavior. When true, POE::Component::Client::TCP
437 will automatically shutdown when it encounters an error.
438
440 The SEE ALSO section in POE contains a table of contents covering the
441 entire POE distribution.
442 POE::Component::Server::TCP is the server-side counterpart to this
444 module.
445 This component uses and exposes features from POE::Filter,
447 POE::Wheel::SocketFactory, and POE::Wheel::ReadWrite.
448 See "SYNOPSIS" in POE::Wheel::SocketFactory for a more efficient but
450 lower-level way to create clients and servers.
451
453 This looks nothing like what Ann envisioned.
454 POE::Component::Client::TCP is a generic client. As such, it's not
456 tuned for any particular task. While it handles the common cases well
457 and with a minimum of code, it may not be suitable for everything.
458
460 POE::Component::Client::TCP is Copyright 2001-2013 by Rocco Caputo.
461 All rights are reserved. POE::Component::Client::TCP is free software,
462 and it may be redistributed and/or modified under the same terms as
463 Perl itself.
464 POE::Component::Client::TCP is based on code, used with permission,
466 from Ann Barcomb <kudra@domaintje.com>.
467 POE::Component::Client::TCP is based on code, used with permission,
469 from Jos Boumans <kane@cpan.org>.
470perl v5.30.0 2019-07-26 POE::Component::Client::TCP(3)