ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent/Handle.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.197 by root, Tue Aug 31 00:59:55 2010 UTC vs.
Revision 1.240 by root, Tue Dec 17 16:43:15 2013 UTC

… …
11 11
12 my $hdl; $hdl = new AnyEvent::Handle 12 my $hdl; $hdl = new AnyEvent::Handle
13 fh => \*STDIN, 13 fh => \*STDIN,
14 on_error => sub { 14 on_error => sub {
15 my ($hdl, $fatal, $msg) = @_; 15 my ($hdl, $fatal, $msg) = @_;
16 warn "got error $msg\n"; 16 AE::log error => $msg;
17 $hdl->destroy; 17 $hdl->destroy;
18 $cv->send; 18 $cv->send;
19 }; 19 };
20 20
21 # send some request line 21 # send some request line
22 $hdl->push_write ("getinfo\015\012"); 22 $hdl->push_write ("getinfo\015\012");
23 23
24 # read the response line 24 # read the response line
25 $hdl->push_read (line => sub { 25 $hdl->push_read (line => sub {
26 my ($hdl, $line) = @_; 26 my ($hdl, $line) = @_;
27 warn "got line <$line>\n"; 27 say "got line <$line>";
28 $cv->send; 28 $cv->send;
29 }); 29 });
30 30
31 $cv->recv; 31 $cv->recv;
32 32
33=head1 DESCRIPTION 33=head1 DESCRIPTION
34 34
35This module is a helper module to make it easier to do event-based I/O on 35This is a helper module to make it easier to do event-based I/O on
36stream-based filehandles (sockets, pipes or other stream things). 36stream-based filehandles (sockets, pipes, and other stream things).
37 37
38The L<AnyEvent::Intro> tutorial contains some well-documented 38The L<AnyEvent::Intro> tutorial contains some well-documented
39AnyEvent::Handle examples. 39AnyEvent::Handle examples.
40 40
41In the following, when the documentation refers to of "bytes" then this 41In the following, where the documentation refers to "bytes", it means
42means characters. As sysread and syswrite are used for all I/O, their 42characters. As sysread and syswrite are used for all I/O, their
43treatment of characters applies to this module as well. 43treatment of characters applies to this module as well.
44 44
45At the very minimum, you should specify C<fh> or C<connect>, and the 45At the very minimum, you should specify C<fh> or C<connect>, and the
46C<on_error> callback. 46C<on_error> callback.
47 47
… …
75 } 75 }
76 76
77 \&$func 77 \&$func
78} 78}
79 79
80sub MAX_READ_SIZE() { 131072 }
81
80=head1 METHODS 82=head1 METHODS
81 83
82=over 4 84=over 4
83 85
84=item $handle = B<new> AnyEvent::Handle fh => $filehandle, key => value... 86=item $handle = B<new> AnyEvent::Handle fh => $filehandle, key => value...
… …
112=over 4 114=over 4
113 115
114=item on_prepare => $cb->($handle) 116=item on_prepare => $cb->($handle)
115 117
116This (rarely used) callback is called before a new connection is 118This (rarely used) callback is called before a new connection is
117attempted, but after the file handle has been created. It could be used to 119attempted, but after the file handle has been created (you can access that
120file handle via C<< $handle->{fh} >>). It could be used to prepare the
118prepare the file handle with parameters required for the actual connect 121file handle with parameters required for the actual connect (as opposed to
119(as opposed to settings that can be changed when the connection is already 122settings that can be changed when the connection is already established).
120established).
121 123
122The return value of this callback should be the connect timeout value in 124The return value of this callback should be the connect timeout value in
123seconds (or C<0>, or C<undef>, or the empty list, to indicate the default 125seconds (or C<0>, or C<undef>, or the empty list, to indicate that the
124timeout is to be used). 126default timeout is to be used).
125 127
126=item on_connect => $cb->($handle, $host, $port, $retry->()) 128=item on_connect => $cb->($handle, $host, $port, $retry->())
127 129
128This callback is called when a connection has been successfully established. 130This callback is called when a connection has been successfully established.
129 131
130The actual numeric host and port (the socket peername) are passed as 132The peer's numeric host and port (the socket peername) are passed as
131parameters, together with a retry callback. 133parameters, together with a retry callback. At the time it is called the
134read and write queues, EOF status, TLS status and similar properties of
135the handle will have been reset.
132 136
137It is not allowed to use the read or write queues while the handle object
138is connecting.
139
133When, for some reason, the handle is not acceptable, then calling 140If, for some reason, the handle is not acceptable, calling C<$retry> will
134C<$retry> will continue with the next connection target (in case of 141continue with the next connection target (in case of multi-homed hosts or
135multi-homed hosts or SRV records there can be multiple connection 142SRV records there can be multiple connection endpoints). The C<$retry>
136endpoints). At the time it is called the read and write queues, eof 143callback can be invoked after the connect callback returns, i.e. one can
137status, tls status and similar properties of the handle will have been 144start a handshake and then decide to retry with the next host if the
138reset. 145handshake fails.
139 146
140In most cases, ignoring the C<$retry> parameter is the way to go. 147In most cases, you should ignore the C<$retry> parameter.
141 148
142=item on_connect_error => $cb->($handle, $message) 149=item on_connect_error => $cb->($handle, $message)
143 150
144This callback is called when the connection could not be 151This callback is called when the connection could not be
145established. C<$!> will contain the relevant error code, and C<$message> a 152established. C<$!> will contain the relevant error code, and C<$message> a
… …
152 159
153=item on_error => $cb->($handle, $fatal, $message) 160=item on_error => $cb->($handle, $fatal, $message)
154 161
155This is the error callback, which is called when, well, some error 162This is the error callback, which is called when, well, some error
156occured, such as not being able to resolve the hostname, failure to 163occured, such as not being able to resolve the hostname, failure to
157connect or a read error. 164connect, or a read error.
158 165
159Some errors are fatal (which is indicated by C<$fatal> being true). On 166Some errors are fatal (which is indicated by C<$fatal> being true). On
160fatal errors the handle object will be destroyed (by a call to C<< -> 167fatal errors the handle object will be destroyed (by a call to C<< ->
161destroy >>) after invoking the error callback (which means you are free to 168destroy >>) after invoking the error callback (which means you are free to
162examine the handle object). Examples of fatal errors are an EOF condition 169examine the handle object). Examples of fatal errors are an EOF condition
163with active (but unsatisifable) read watchers (C<EPIPE>) or I/O errors. In 170with active (but unsatisfiable) read watchers (C<EPIPE>) or I/O errors. In
164cases where the other side can close the connection at their will it is 171cases where the other side can close the connection at will, it is
165often easiest to not report C<EPIPE> errors in this callback. 172often easiest to not report C<EPIPE> errors in this callback.
166 173
167AnyEvent::Handle tries to find an appropriate error code for you to check 174AnyEvent::Handle tries to find an appropriate error code for you to check
168against, but in some cases (TLS errors), this does not work well. It is 175against, but in some cases (TLS errors), this does not work well.
169recommended to always output the C<$message> argument in human-readable
170error messages (it's usually the same as C<"$!">).
171 176
177If you report the error to the user, it is recommended to always output
178the C<$message> argument in human-readable error messages (you don't need
179to report C<"$!"> if you report C<$message>).
180
181If you want to react programmatically to the error, then looking at C<$!>
182and comparing it against some of the documented C<Errno> values is usually
183better than looking at the C<$message>.
184
172Non-fatal errors can be retried by simply returning, but it is recommended 185Non-fatal errors can be retried by returning, but it is recommended
173to simply ignore this parameter and instead abondon the handle object 186to simply ignore this parameter and instead abondon the handle object
174when this callback is invoked. Examples of non-fatal errors are timeouts 187when this callback is invoked. Examples of non-fatal errors are timeouts
175C<ETIMEDOUT>) or badly-formatted data (C<EBADMSG>). 188C<ETIMEDOUT>) or badly-formatted data (C<EBADMSG>).
176 189
177On callback entrance, the value of C<$!> contains the operating system 190On entry to the callback, the value of C<$!> contains the operating
178error code (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT>, C<EBADMSG> or 191system error code (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT>, C<EBADMSG> or
179C<EPROTO>). 192C<EPROTO>).
180 193
181While not mandatory, it is I<highly> recommended to set this callback, as 194While not mandatory, it is I<highly> recommended to set this callback, as
182you will not be notified of errors otherwise. The default simply calls 195you will not be notified of errors otherwise. The default just calls
183C<croak>. 196C<croak>.
184 197
185=item on_read => $cb->($handle) 198=item on_read => $cb->($handle)
186 199
187This sets the default read callback, which is called when data arrives 200This sets the default read callback, which is called when data arrives
… …
195the beginning from it. 208the beginning from it.
196 209
197You can also call C<< ->push_read (...) >> or any other function that 210You can also call C<< ->push_read (...) >> or any other function that
198modifies the read queue. Or do both. Or ... 211modifies the read queue. Or do both. Or ...
199 212
200When an EOF condition is detected then AnyEvent::Handle will first try to 213When an EOF condition is detected, AnyEvent::Handle will first try to
201feed all the remaining data to the queued callbacks and C<on_read> before 214feed all the remaining data to the queued callbacks and C<on_read> before
202calling the C<on_eof> callback. If no progress can be made, then a fatal 215calling the C<on_eof> callback. If no progress can be made, then a fatal
203error will be raised (with C<$!> set to C<EPIPE>). 216error will be raised (with C<$!> set to C<EPIPE>).
204 217
205Note that, unlike requests in the read queue, an C<on_read> callback 218Note that, unlike requests in the read queue, an C<on_read> callback
… …
223If an EOF condition has been detected but no C<on_eof> callback has been 236If an EOF condition has been detected but no C<on_eof> callback has been
224set, then a fatal error will be raised with C<$!> set to <0>. 237set, then a fatal error will be raised with C<$!> set to <0>.
225 238
226=item on_drain => $cb->($handle) 239=item on_drain => $cb->($handle)
227 240
228This sets the callback that is called when the write buffer becomes empty 241This sets the callback that is called once when the write buffer becomes
229(or when the callback is set and the buffer is empty already). 242empty (and immediately when the handle object is created).
230 243
231To append to the write buffer, use the C<< ->push_write >> method. 244To append to the write buffer, use the C<< ->push_write >> method.
232 245
233This callback is useful when you don't want to put all of your write data 246This callback is useful when you don't want to put all of your write data
234into the queue at once, for example, when you want to write the contents 247into the queue at once, for example, when you want to write the contents
… …
246many seconds pass without a successful read or write on the underlying 259many seconds pass without a successful read or write on the underlying
247file handle (or a call to C<timeout_reset>), the C<on_timeout> callback 260file handle (or a call to C<timeout_reset>), the C<on_timeout> callback
248will be invoked (and if that one is missing, a non-fatal C<ETIMEDOUT> 261will be invoked (and if that one is missing, a non-fatal C<ETIMEDOUT>
249error will be raised). 262error will be raised).
250 263
251There are three variants of the timeouts that work fully independent 264There are three variants of the timeouts that work independently of each
252of each other, for both read and write, just read, and just write: 265other, for both read and write (triggered when nothing was read I<OR>
266written), just read (triggered when nothing was read), and just write:
253C<timeout>, C<rtimeout> and C<wtimeout>, with corresponding callbacks 267C<timeout>, C<rtimeout> and C<wtimeout>, with corresponding callbacks
254C<on_timeout>, C<on_rtimeout> and C<on_wtimeout>, and reset functions 268C<on_timeout>, C<on_rtimeout> and C<on_wtimeout>, and reset functions
255C<timeout_reset>, C<rtimeout_reset>, and C<wtimeout_reset>. 269C<timeout_reset>, C<rtimeout_reset>, and C<wtimeout_reset>.
256 270
257Note that timeout processing is also active when you currently do not have 271Note that timeout processing is active even when you do not have any
258any outstanding read or write requests: If you plan to keep the connection 272outstanding read or write requests: If you plan to keep the connection
259idle then you should disable the timout temporarily or ignore the timeout 273idle then you should disable the timeout temporarily or ignore the
260in the C<on_timeout> callback, in which case AnyEvent::Handle will simply 274timeout in the corresponding C<on_timeout> callback, in which case
261restart the timeout. 275AnyEvent::Handle will simply restart the timeout.
262 276
263Zero (the default) disables this timeout. 277Zero (the default) disables the corresponding timeout.
264 278
265=item on_timeout => $cb->($handle) 279=item on_timeout => $cb->($handle)
280
281=item on_rtimeout => $cb->($handle)
282
283=item on_wtimeout => $cb->($handle)
266 284
267Called whenever the inactivity timeout passes. If you return from this 285Called whenever the inactivity timeout passes. If you return from this
268callback, then the timeout will be reset as if some activity had happened, 286callback, then the timeout will be reset as if some activity had happened,
269so this condition is not fatal in any way. 287so this condition is not fatal in any way.
270 288
… …
278be configured to accept only so-and-so much data that it cannot act on 296be configured to accept only so-and-so much data that it cannot act on
279(for example, when expecting a line, an attacker could send an unlimited 297(for example, when expecting a line, an attacker could send an unlimited
280amount of data without a callback ever being called as long as the line 298amount of data without a callback ever being called as long as the line
281isn't finished). 299isn't finished).
282 300
301=item wbuf_max => <bytes>
302
303If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>)
304when the write buffer ever (strictly) exceeds this size. This is useful to
305avoid some forms of denial-of-service attacks.
306
307Although the units of this parameter is bytes, this is the I<raw> number
308of bytes not yet accepted by the kernel. This can make a difference when
309you e.g. use TLS, as TLS typically makes your write data larger (but it
310can also make it smaller due to compression).
311
312As an example of when this limit is useful, take a chat server that sends
313chat messages to a client. If the client does not read those in a timely
314manner then the send buffer in the server would grow unbounded.
315
283=item autocork => <boolean> 316=item autocork => <boolean>
284 317
285When disabled (the default), then C<push_write> will try to immediately 318When disabled (the default), C<push_write> will try to immediately
286write the data to the handle, if possible. This avoids having to register 319write the data to the handle if possible. This avoids having to register
287a write watcher and wait for the next event loop iteration, but can 320a write watcher and wait for the next event loop iteration, but can
288be inefficient if you write multiple small chunks (on the wire, this 321be inefficient if you write multiple small chunks (on the wire, this
289disadvantage is usually avoided by your kernel's nagle algorithm, see 322disadvantage is usually avoided by your kernel's nagle algorithm, see
290C<no_delay>, but this option can save costly syscalls). 323C<no_delay>, but this option can save costly syscalls).
291 324
292When enabled, then writes will always be queued till the next event loop 325When enabled, writes will always be queued till the next event loop
293iteration. This is efficient when you do many small writes per iteration, 326iteration. This is efficient when you do many small writes per iteration,
294but less efficient when you do a single write only per iteration (or when 327but less efficient when you do a single write only per iteration (or when
295the write buffer often is full). It also increases write latency. 328the write buffer often is full). It also increases write latency.
296 329
297=item no_delay => <boolean> 330=item no_delay => <boolean>
… …
301the Nagle algorithm, and usually it is beneficial. 334the Nagle algorithm, and usually it is beneficial.
302 335
303In some situations you want as low a delay as possible, which can be 336In some situations you want as low a delay as possible, which can be
304accomplishd by setting this option to a true value. 337accomplishd by setting this option to a true value.
305 338
306The default is your opertaing system's default behaviour (most likely 339The default is your operating system's default behaviour (most likely
307enabled), this option explicitly enables or disables it, if possible. 340enabled). This option explicitly enables or disables it, if possible.
308 341
309=item keepalive => <boolean> 342=item keepalive => <boolean>
310 343
311Enables (default disable) the SO_KEEPALIVE option on the stream socket: 344Enables (default disable) the SO_KEEPALIVE option on the stream socket:
312normally, TCP connections have no time-out once established, so TCP 345normally, TCP connections have no time-out once established, so TCP
313connections, once established, can stay alive forever even when the other 346connections, once established, can stay alive forever even when the other
314side has long gone. TCP keepalives are a cheap way to take down long-lived 347side has long gone. TCP keepalives are a cheap way to take down long-lived
315TCP connections whent he other side becomes unreachable. While the default 348TCP connections when the other side becomes unreachable. While the default
316is OS-dependent, TCP keepalives usually kick in after around two hours, 349is OS-dependent, TCP keepalives usually kick in after around two hours,
317and, if the other side doesn't reply, take down the TCP connection some 10 350and, if the other side doesn't reply, take down the TCP connection some 10
318to 15 minutes later. 351to 15 minutes later.
319 352
320It is harmless to specify this option for file handles that do not support 353It is harmless to specify this option for file handles that do not support
… …
338already have occured on BSD systems), but at least it will protect you 371already have occured on BSD systems), but at least it will protect you
339from most attacks. 372from most attacks.
340 373
341=item read_size => <bytes> 374=item read_size => <bytes>
342 375
343The default read block size (the amount of bytes this module will 376The initial read block size, the number of bytes this module will try
344try to read during each loop iteration, which affects memory 377to read during each loop iteration. Each handle object will consume
345requirements). Default: C<8192>. 378at least this amount of memory for the read buffer as well, so when
379handling many connections watch out for memory requirements). See also
380C<max_read_size>. Default: C<2048>.
381
382=item max_read_size => <bytes>
383
384The maximum read buffer size used by the dynamic adjustment
385algorithm: Each time AnyEvent::Handle can read C<read_size> bytes in
386one go it will double C<read_size> up to the maximum given by this
387option. Default: C<131072> or C<read_size>, whichever is higher.
346 388
347=item low_water_mark => <bytes> 389=item low_water_mark => <bytes>
348 390
349Sets the amount of bytes (default: C<0>) that make up an "empty" write 391Sets the number of bytes (default: C<0>) that make up an "empty" write
350buffer: If the write reaches this size or gets even samller it is 392buffer: If the buffer reaches this size or gets even samller it is
351considered empty. 393considered empty.
352 394
353Sometimes it can be beneficial (for performance reasons) to add data to 395Sometimes it can be beneficial (for performance reasons) to add data to
354the write buffer before it is fully drained, but this is a rare case, as 396the write buffer before it is fully drained, but this is a rare case, as
355the operating system kernel usually buffers data as well, so the default 397the operating system kernel usually buffers data as well, so the default
356is good in almost all cases. 398is good in almost all cases.
357 399
358=item linger => <seconds> 400=item linger => <seconds>
359 401
360If non-zero (default: C<3600>), then the destructor of the 402If this is non-zero (default: C<3600>), the destructor of the
361AnyEvent::Handle object will check whether there is still outstanding 403AnyEvent::Handle object will check whether there is still outstanding
362write data and will install a watcher that will write this data to the 404write data and will install a watcher that will write this data to the
363socket. No errors will be reported (this mostly matches how the operating 405socket. No errors will be reported (this mostly matches how the operating
364system treats outstanding data at socket close time). 406system treats outstanding data at socket close time).
365 407
… …
372A string used to identify the remote site - usually the DNS hostname 414A string used to identify the remote site - usually the DNS hostname
373(I<not> IDN!) used to create the connection, rarely the IP address. 415(I<not> IDN!) used to create the connection, rarely the IP address.
374 416
375Apart from being useful in error messages, this string is also used in TLS 417Apart from being useful in error messages, this string is also used in TLS
376peername verification (see C<verify_peername> in L<AnyEvent::TLS>). This 418peername verification (see C<verify_peername> in L<AnyEvent::TLS>). This
377verification will be skipped when C<peername> is not specified or 419verification will be skipped when C<peername> is not specified or is
378C<undef>. 420C<undef>.
379 421
380=item tls => "accept" | "connect" | Net::SSLeay::SSL object 422=item tls => "accept" | "connect" | Net::SSLeay::SSL object
381 423
382When this parameter is given, it enables TLS (SSL) mode, that means 424When this parameter is given, it enables TLS (SSL) mode, that means
… …
387appropriate error message. 429appropriate error message.
388 430
389TLS mode requires Net::SSLeay to be installed (it will be loaded 431TLS mode requires Net::SSLeay to be installed (it will be loaded
390automatically when you try to create a TLS handle): this module doesn't 432automatically when you try to create a TLS handle): this module doesn't
391have a dependency on that module, so if your module requires it, you have 433have a dependency on that module, so if your module requires it, you have
392to add the dependency yourself. 434to add the dependency yourself. If Net::SSLeay cannot be loaded or is too
435old, you get an C<EPROTO> error.
393 436
394Unlike TCP, TLS has a server and client side: for the TLS server side, use 437Unlike TCP, TLS has a server and client side: for the TLS server side, use
395C<accept>, and for the TLS client side of a connection, use C<connect> 438C<accept>, and for the TLS client side of a connection, use C<connect>
396mode. 439mode.
397 440
… …
408B<IMPORTANT:> since Net::SSLeay "objects" are really only integers, 451B<IMPORTANT:> since Net::SSLeay "objects" are really only integers,
409passing in the wrong integer will lead to certain crash. This most often 452passing in the wrong integer will lead to certain crash. This most often
410happens when one uses a stylish C<< tls => 1 >> and is surprised about the 453happens when one uses a stylish C<< tls => 1 >> and is surprised about the
411segmentation fault. 454segmentation fault.
412 455
413See the C<< ->starttls >> method for when need to start TLS negotiation later. 456Use the C<< ->starttls >> method if you need to start TLS negotiation later.
414 457
415=item tls_ctx => $anyevent_tls 458=item tls_ctx => $anyevent_tls
416 459
417Use the given C<AnyEvent::TLS> object to create the new TLS connection 460Use the given C<AnyEvent::TLS> object to create the new TLS connection
418(unless a connection object was specified directly). If this parameter is 461(unless a connection object was specified directly). If this
419missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>. 462parameter is missing (or C<undef>), then AnyEvent::Handle will use
463C<AnyEvent::Handle::TLS_CTX>.
420 464
421Instead of an object, you can also specify a hash reference with C<< key 465Instead of an object, you can also specify a hash reference with C<< key
422=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a 466=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a
423new TLS context object. 467new TLS context object.
424 468
… …
433 477
434TLS handshake failures will not cause C<on_error> to be invoked when this 478TLS handshake failures will not cause C<on_error> to be invoked when this
435callback is in effect, instead, the error message will be passed to C<on_starttls>. 479callback is in effect, instead, the error message will be passed to C<on_starttls>.
436 480
437Without this callback, handshake failures lead to C<on_error> being 481Without this callback, handshake failures lead to C<on_error> being
438called, as normal. 482called as usual.
439 483
440Note that you cannot call C<starttls> right again in this callback. If you 484Note that you cannot just call C<starttls> again in this callback. If you
441need to do that, start an zero-second timer instead whose callback can 485need to do that, start an zero-second timer instead whose callback can
442then call C<< ->starttls >> again. 486then call C<< ->starttls >> again.
443 487
444=item on_stoptls => $cb->($handle) 488=item on_stoptls => $cb->($handle)
445 489
… …
452callback. 496callback.
453 497
454This callback will only be called on TLS shutdowns, not when the 498This callback will only be called on TLS shutdowns, not when the
455underlying handle signals EOF. 499underlying handle signals EOF.
456 500
457=item json => JSON or JSON::XS object 501=item json => L<JSON>, L<JSON::PP> or L<JSON::XS> object
458 502
459This is the json coder object used by the C<json> read and write types. 503This is the json coder object used by the C<json> read and write types.
460 504
461If you don't supply it, then AnyEvent::Handle will create and use a 505If you don't supply it, then AnyEvent::Handle will create and use a
462suitable one (on demand), which will write and expect UTF-8 encoded JSON 506suitable one (on demand), which will write and expect UTF-8 encoded JSON
463texts. 507texts.
464 508
509=item cbor => L<CBOR::XS> object
510
511This is the cbor coder object used by the C<cbor> read and write types.
512
513If you don't supply it, then AnyEvent::Handle will create and use a
514suitable one (on demand), which will write CBOR without using extensions,
515if possible. texts.
516
465Note that you are responsible to depend on the JSON module if you want to 517Note that you are responsible to depend on the L<CBOR::XS> module if you
466use this functionality, as AnyEvent does not have a dependency itself. 518want to use this functionality, as AnyEvent does not have a dependency on
519it itself.
467 520
468=back 521=back
469 522
470=cut 523=cut
471 524
… …
493 $self->{connect}[0], 546 $self->{connect}[0],
494 $self->{connect}[1], 547 $self->{connect}[1],
495 sub { 548 sub {
496 my ($fh, $host, $port, $retry) = @_; 549 my ($fh, $host, $port, $retry) = @_;
497 550
551 delete $self->{_connect}; # no longer needed
552
498 if ($fh) { 553 if ($fh) {
499 $self->{fh} = $fh; 554 $self->{fh} = $fh;
500 555
501 delete $self->{_skip_drain_rbuf}; 556 delete $self->{_skip_drain_rbuf};
502 $self->_start; 557 $self->_start;
… …
509 }); 564 });
510 565
511 } else { 566 } else {
512 if ($self->{on_connect_error}) { 567 if ($self->{on_connect_error}) {
513 $self->{on_connect_error}($self, "$!"); 568 $self->{on_connect_error}($self, "$!");
514 $self->destroy; 569 $self->destroy if $self;
515 } else { 570 } else {
516 $self->_error ($!, 1); 571 $self->_error ($!, 1);
517 } 572 }
518 } 573 }
519 }, 574 },
520 sub { 575 sub {
521 local $self->{fh} = $_[0]; 576 local $self->{fh} = $_[0];
522 577
523 $self->{on_prepare} 578 $self->{on_prepare}
524 ? $self->{on_prepare}->($self) 579 ? $self->{on_prepare}->($self)
525 : () 580 : ()
526 } 581 }
527 ); 582 );
528 } 583 }
529 584
… …
547 602
548 $self->{_activity} = 603 $self->{_activity} =
549 $self->{_ractivity} = 604 $self->{_ractivity} =
550 $self->{_wactivity} = AE::now; 605 $self->{_wactivity} = AE::now;
551 606
607 $self->{read_size} ||= 2048;
608 $self->{max_read_size} = $self->{read_size}
609 if $self->{read_size} > ($self->{max_read_size} || MAX_READ_SIZE);
610
552 $self->timeout (delete $self->{timeout} ) if $self->{timeout}; 611 $self->timeout (delete $self->{timeout} ) if $self->{timeout};
553 $self->rtimeout (delete $self->{rtimeout} ) if $self->{rtimeout}; 612 $self->rtimeout (delete $self->{rtimeout} ) if $self->{rtimeout};
554 $self->wtimeout (delete $self->{wtimeout} ) if $self->{wtimeout}; 613 $self->wtimeout (delete $self->{wtimeout} ) if $self->{wtimeout};
555 614
556 $self->no_delay (delete $self->{no_delay} ) if exists $self->{no_delay} && $self->{no_delay}; 615 $self->no_delay (delete $self->{no_delay} ) if exists $self->{no_delay} && $self->{no_delay};
… …
559 $self->oobinline (exists $self->{oobinline} ? delete $self->{oobinline} : 1); 618 $self->oobinline (exists $self->{oobinline} ? delete $self->{oobinline} : 1);
560 619
561 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx}) 620 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx})
562 if $self->{tls}; 621 if $self->{tls};
563 622
564 $self->on_drain (delete $self->{on_drain}) if $self->{on_drain}; 623 $self->on_drain (delete $self->{on_drain} ) if $self->{on_drain};
565 624
566 $self->start_read 625 $self->start_read
567 if $self->{on_read} || @{ $self->{_queue} }; 626 if $self->{on_read} || @{ $self->{_queue} };
568 627
569 $self->_drain_wbuf; 628 $self->_drain_wbuf;
… …
645=cut 704=cut
646 705
647sub no_delay { 706sub no_delay {
648 $_[0]{no_delay} = $_[1]; 707 $_[0]{no_delay} = $_[1];
649 708
650 eval {
651 local $SIG{__DIE__};
652 setsockopt $_[0]{fh}, Socket::IPPROTO_TCP (), Socket::TCP_NODELAY (), int $_[1] 709 setsockopt $_[0]{fh}, Socket::IPPROTO_TCP (), Socket::TCP_NODELAY (), int $_[1]
653 if $_[0]{fh}; 710 if $_[0]{fh};
654 };
655} 711}
656 712
657=item $handle->keepalive ($boolean) 713=item $handle->keepalive ($boolean)
658 714
659Enables or disables the C<keepalive> setting (see constructor argument of 715Enables or disables the C<keepalive> setting (see constructor argument of
… …
727 783
728=item $handle->rbuf_max ($max_octets) 784=item $handle->rbuf_max ($max_octets)
729 785
730Configures the C<rbuf_max> setting (C<undef> disables it). 786Configures the C<rbuf_max> setting (C<undef> disables it).
731 787
788=item $handle->wbuf_max ($max_octets)
789
790Configures the C<wbuf_max> setting (C<undef> disables it).
791
732=cut 792=cut
733 793
734sub rbuf_max { 794sub rbuf_max {
735 $_[0]{rbuf_max} = $_[1]; 795 $_[0]{rbuf_max} = $_[1];
736} 796}
737 797
798sub wbuf_max {
799 $_[0]{wbuf_max} = $_[1];
800}
801
738############################################################################# 802#############################################################################
739 803
740=item $handle->timeout ($seconds) 804=item $handle->timeout ($seconds)
741 805
742=item $handle->rtimeout ($seconds) 806=item $handle->rtimeout ($seconds)
743 807
744=item $handle->wtimeout ($seconds) 808=item $handle->wtimeout ($seconds)
745 809
746Configures (or disables) the inactivity timeout. 810Configures (or disables) the inactivity timeout.
811
812The timeout will be checked instantly, so this method might destroy the
813handle before it returns.
747 814
748=item $handle->timeout_reset 815=item $handle->timeout_reset
749 816
750=item $handle->rtimeout_reset 817=item $handle->rtimeout_reset
751 818
… …
768 $_[0]{$on_timeout} = $_[1]; 835 $_[0]{$on_timeout} = $_[1];
769 }; 836 };
770 837
771 *$timeout = sub { 838 *$timeout = sub {
772 my ($self, $new_value) = @_; 839 my ($self, $new_value) = @_;
840
841 $new_value >= 0
842 or Carp::croak "AnyEvent::Handle->$timeout called with negative timeout ($new_value), caught";
773 843
774 $self->{$timeout} = $new_value; 844 $self->{$timeout} = $new_value;
775 delete $self->{$tw}; &$cb; 845 delete $self->{$tw}; &$cb;
776 }; 846 };
777 847
… …
832 902
833The write queue is very simple: you can add data to its end, and 903The write queue is very simple: you can add data to its end, and
834AnyEvent::Handle will automatically try to get rid of it for you. 904AnyEvent::Handle will automatically try to get rid of it for you.
835 905
836When data could be written and the write buffer is shorter then the low 906When data could be written and the write buffer is shorter then the low
837water mark, the C<on_drain> callback will be invoked. 907water mark, the C<on_drain> callback will be invoked once.
838 908
839=over 4 909=over 4
840 910
841=item $handle->on_drain ($cb) 911=item $handle->on_drain ($cb)
842 912
… …
857 if $cb && $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf}); 927 if $cb && $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf});
858} 928}
859 929
860=item $handle->push_write ($data) 930=item $handle->push_write ($data)
861 931
862Queues the given scalar to be written. You can push as much data as you 932Queues the given scalar to be written. You can push as much data as
863want (only limited by the available memory), as C<AnyEvent::Handle> 933you want (only limited by the available memory and C<wbuf_max>), as
864buffers it independently of the kernel. 934C<AnyEvent::Handle> buffers it independently of the kernel.
865 935
866This method may invoke callbacks (and therefore the handle might be 936This method may invoke callbacks (and therefore the handle might be
867destroyed after it returns). 937destroyed after it returns).
868 938
869=cut 939=cut
… …
897 $cb->() unless $self->{autocork}; 967 $cb->() unless $self->{autocork};
898 968
899 # if still data left in wbuf, we need to poll 969 # if still data left in wbuf, we need to poll
900 $self->{_ww} = AE::io $self->{fh}, 1, $cb 970 $self->{_ww} = AE::io $self->{fh}, 1, $cb
901 if length $self->{wbuf}; 971 if length $self->{wbuf};
972
973 if (
974 defined $self->{wbuf_max}
975 && $self->{wbuf_max} < length $self->{wbuf}
976 ) {
977 $self->_error (Errno::ENOSPC, 1), return;
978 }
902 }; 979 };
903} 980}
904 981
905our %WH; 982our %WH;
906 983
… …
985 1062
986The generated JSON text is guaranteed not to contain any newlines: While 1063The generated JSON text is guaranteed not to contain any newlines: While
987this module doesn't need delimiters after or between JSON texts to be 1064this module doesn't need delimiters after or between JSON texts to be
988able to read them, many other languages depend on that. 1065able to read them, many other languages depend on that.
989 1066
990A simple RPC protocol that interoperates easily with others is to send 1067A simple RPC protocol that interoperates easily with other languages is
991JSON arrays (or objects, although arrays are usually the better choice as 1068to send JSON arrays (or objects, although arrays are usually the better
992they mimic how function argument passing works) and a newline after each 1069choice as they mimic how function argument passing works) and a newline
993JSON text: 1070after each JSON text:
994 1071
995 $handle->push_write (json => ["method", "arg1", "arg2"]); # whatever 1072 $handle->push_write (json => ["method", "arg1", "arg2"]); # whatever
996 $handle->push_write ("\012"); 1073 $handle->push_write ("\012");
997 1074
998An AnyEvent::Handle receiver would simply use the C<json> read type and 1075An AnyEvent::Handle receiver would simply use the C<json> read type and
… …
1001 $handle->push_read (json => sub { my $array = $_[1]; ... }); 1078 $handle->push_read (json => sub { my $array = $_[1]; ... });
1002 1079
1003Other languages could read single lines terminated by a newline and pass 1080Other languages could read single lines terminated by a newline and pass
1004this line into their JSON decoder of choice. 1081this line into their JSON decoder of choice.
1005 1082
1083=item cbor => $perl_scalar
1084
1085Encodes the given scalar into a CBOR value. Unless you provide your own
1086L<CBOR::XS> object, this means it will be encoded to a CBOR string not
1087using any extensions, if possible.
1088
1089CBOR values are self-delimiting, so you can write CBOR at one end of
1090a handle and read them at the other end without using any additional
1091framing.
1092
1093A simple nd very very fast RPC protocol that interoperates with
1094other languages is to send CBOR and receive CBOR values (arrays are
1095recommended):
1096
1097 $handle->push_write (cbor => ["method", "arg1", "arg2"]); # whatever
1098
1099An AnyEvent::Handle receiver would simply use the C<cbor> read type:
1100
1101 $handle->push_read (cbor => sub { my $array = $_[1]; ... });
1102
1006=cut 1103=cut
1007 1104
1008sub json_coder() { 1105sub json_coder() {
1009 eval { require JSON::XS; JSON::XS->new->utf8 } 1106 eval { require JSON::XS; JSON::XS->new->utf8 }
1010 || do { require JSON; JSON->new->utf8 } 1107 || do { require JSON::PP; JSON::PP->new->utf8 }
1011} 1108}
1012 1109
1013register_write_type json => sub { 1110register_write_type json => sub {
1014 my ($self, $ref) = @_; 1111 my ($self, $ref) = @_;
1015 1112
1016 my $json = $self->{json} ||= json_coder; 1113 ($self->{json} ||= json_coder)
1017
1018 $json->encode ($ref) 1114 ->encode ($ref)
1115};
1116
1117sub cbor_coder() {
1118 require CBOR::XS;
1119 CBOR::XS->new
1120}
1121
1122register_write_type cbor => sub {
1123 my ($self, $scalar) = @_;
1124
1125 ($self->{cbor} ||= cbor_coder)
1126 ->encode ($scalar)
1019}; 1127};
1020 1128
1021=item storable => $reference 1129=item storable => $reference
1022 1130
1023Freezes the given reference using L<Storable> and writes it to the 1131Freezes the given reference using L<Storable> and writes it to the
… …
1026=cut 1134=cut
1027 1135
1028register_write_type storable => sub { 1136register_write_type storable => sub {
1029 my ($self, $ref) = @_; 1137 my ($self, $ref) = @_;
1030 1138
1031 require Storable; 1139 require Storable unless $Storable::VERSION;
1032 1140
1033 pack "w/a*", Storable::nfreeze ($ref) 1141 pack "w/a*", Storable::nfreeze ($ref)
1034}; 1142};
1035 1143
1036=back 1144=back
… …
1041before it was actually written. One way to do that is to replace your 1149before it was actually written. One way to do that is to replace your
1042C<on_drain> handler by a callback that shuts down the socket (and set 1150C<on_drain> handler by a callback that shuts down the socket (and set
1043C<low_water_mark> to C<0>). This method is a shorthand for just that, and 1151C<low_water_mark> to C<0>). This method is a shorthand for just that, and
1044replaces the C<on_drain> callback with: 1152replaces the C<on_drain> callback with:
1045 1153
1046 sub { shutdown $_[0]{fh}, 1 } # for push_shutdown 1154 sub { shutdown $_[0]{fh}, 1 }
1047 1155
1048This simply shuts down the write side and signals an EOF condition to the 1156This simply shuts down the write side and signals an EOF condition to the
1049the peer. 1157the peer.
1050 1158
1051You can rely on the normal read queue and C<on_eof> handling 1159You can rely on the normal read queue and C<on_eof> handling
… …
1073 1181
1074Whenever the given C<type> is used, C<push_write> will the function with 1182Whenever the given C<type> is used, C<push_write> will the function with
1075the handle object and the remaining arguments. 1183the handle object and the remaining arguments.
1076 1184
1077The function is supposed to return a single octet string that will be 1185The function is supposed to return a single octet string that will be
1078appended to the write buffer, so you cna mentally treat this function as a 1186appended to the write buffer, so you can mentally treat this function as a
1079"arguments to on-the-wire-format" converter. 1187"arguments to on-the-wire-format" converter.
1080 1188
1081Example: implement a custom write type C<join> that joins the remaining 1189Example: implement a custom write type C<join> that joins the remaining
1082arguments using the first one. 1190arguments using the first one.
1083 1191
… …
1117partial message has been received so far), or change the read queue with 1225partial message has been received so far), or change the read queue with
1118e.g. C<push_read>. 1226e.g. C<push_read>.
1119 1227
1120In the more complex case, you want to queue multiple callbacks. In this 1228In the more complex case, you want to queue multiple callbacks. In this
1121case, AnyEvent::Handle will call the first queued callback each time new 1229case, AnyEvent::Handle will call the first queued callback each time new
1122data arrives (also the first time it is queued) and removes it when it has 1230data arrives (also the first time it is queued) and remove it when it has
1123done its job (see C<push_read>, below). 1231done its job (see C<push_read>, below).
1124 1232
1125This way you can, for example, push three line-reads, followed by reading 1233This way you can, for example, push three line-reads, followed by reading
1126a chunk of data, and AnyEvent::Handle will execute them in order. 1234a chunk of data, and AnyEvent::Handle will execute them in order.
1127 1235
… …
1272 $self->_drain_rbuf if $cb; 1380 $self->_drain_rbuf if $cb;
1273} 1381}
1274 1382
1275=item $handle->rbuf 1383=item $handle->rbuf
1276 1384
1277Returns the read buffer (as a modifiable lvalue). 1385Returns the read buffer (as a modifiable lvalue). You can also access the
1386read buffer directly as the C<< ->{rbuf} >> member, if you want (this is
1387much faster, and no less clean).
1278 1388
1279You can access the read buffer directly as the C<< ->{rbuf} >> 1389The only operation allowed on the read buffer (apart from looking at it)
1280member, if you want. However, the only operation allowed on the 1390is removing data from its beginning. Otherwise modifying or appending to
1281read buffer (apart from looking at it) is removing data from its 1391it is not allowed and will lead to hard-to-track-down bugs.
1282beginning. Otherwise modifying or appending to it is not allowed and will
1283lead to hard-to-track-down bugs.
1284 1392
1285NOTE: The read buffer should only be used or modified if the C<on_read>, 1393NOTE: The read buffer should only be used or modified in the C<on_read>
1286C<push_read> or C<unshift_read> methods are used. The other read methods 1394callback or when C<push_read> or C<unshift_read> are used with a single
1287automatically manage the read buffer. 1395callback (i.e. untyped). Typed C<push_read> and C<unshift_read> methods
1396will manage the read buffer on their own.
1288 1397
1289=cut 1398=cut
1290 1399
1291sub rbuf : lvalue { 1400sub rbuf : lvalue {
1292 $_[0]{rbuf} 1401 $_[0]{rbuf}
… …
1343 my $cb = pop; 1452 my $cb = pop;
1344 1453
1345 if (@_) { 1454 if (@_) {
1346 my $type = shift; 1455 my $type = shift;
1347 1456
1457 $cb = ($RH{$type} ||= _load_func "$type\::anyevent_read_type"
1348 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::unshift_read") 1458 or Carp::croak "unsupported/unloadable type '$type' passed to AnyEvent::Handle::unshift_read")
1349 ->($self, $cb, @_); 1459 ->($self, $cb, @_);
1350 } 1460 }
1351 1461
1352 unshift @{ $self->{_queue} }, $cb; 1462 unshift @{ $self->{_queue} }, $cb;
1353 $self->_drain_rbuf; 1463 $self->_drain_rbuf;
… …
1375data. 1485data.
1376 1486
1377Example: read 2 bytes. 1487Example: read 2 bytes.
1378 1488
1379 $handle->push_read (chunk => 2, sub { 1489 $handle->push_read (chunk => 2, sub {
1380 warn "yay ", unpack "H*", $_[1]; 1490 say "yay " . unpack "H*", $_[1];
1381 }); 1491 });
1382 1492
1383=cut 1493=cut
1384 1494
1385register_read_type chunk => sub { 1495register_read_type chunk => sub {
… …
1415 1525
1416register_read_type line => sub { 1526register_read_type line => sub {
1417 my ($self, $cb, $eol) = @_; 1527 my ($self, $cb, $eol) = @_;
1418 1528
1419 if (@_ < 3) { 1529 if (@_ < 3) {
1420 # this is more than twice as fast as the generic code below 1530 # this is faster then the generic code below
1421 sub { 1531 sub {
1422 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return; 1532 (my $pos = index $_[0]{rbuf}, "\012") >= 0
1533 or return;
1423 1534
1535 (my $str = substr $_[0]{rbuf}, 0, $pos + 1, "") =~ s/(\015?\012)\Z// or die;
1424 $cb->($_[0], $1, $2); 1536 $cb->($_[0], $str, "$1");
1425 1 1537 1
1426 } 1538 }
1427 } else { 1539 } else {
1428 $eol = quotemeta $eol unless ref $eol; 1540 $eol = quotemeta $eol unless ref $eol;
1429 $eol = qr|^(.*?)($eol)|s; 1541 $eol = qr|^(.*?)($eol)|s;
1430 1542
1431 sub { 1543 sub {
1432 $_[0]{rbuf} =~ s/$eol// or return; 1544 $_[0]{rbuf} =~ s/$eol// or return;
1433 1545
1434 $cb->($_[0], $1, $2); 1546 $cb->($_[0], "$1", "$2");
1435 1 1547 1
1436 } 1548 }
1437 } 1549 }
1438}; 1550};
1439 1551
… …
1461the receive buffer when neither C<$accept> nor C<$reject> match, 1573the receive buffer when neither C<$accept> nor C<$reject> match,
1462and everything preceding and including the match will be accepted 1574and everything preceding and including the match will be accepted
1463unconditionally. This is useful to skip large amounts of data that you 1575unconditionally. This is useful to skip large amounts of data that you
1464know cannot be matched, so that the C<$accept> or C<$reject> regex do not 1576know cannot be matched, so that the C<$accept> or C<$reject> regex do not
1465have to start matching from the beginning. This is purely an optimisation 1577have to start matching from the beginning. This is purely an optimisation
1466and is usually worth only when you expect more than a few kilobytes. 1578and is usually worth it only when you expect more than a few kilobytes.
1467 1579
1468Example: expect a http header, which ends at C<\015\012\015\012>. Since we 1580Example: expect a http header, which ends at C<\015\012\015\012>. Since we
1469expect the header to be very large (it isn't in practise, but...), we use 1581expect the header to be very large (it isn't in practice, but...), we use
1470a skip regex to skip initial portions. The skip regex is tricky in that 1582a skip regex to skip initial portions. The skip regex is tricky in that
1471it only accepts something not ending in either \015 or \012, as these are 1583it only accepts something not ending in either \015 or \012, as these are
1472required for the accept regex. 1584required for the accept regex.
1473 1585
1474 $handle->push_read (regex => 1586 $handle->push_read (regex =>
… …
1487 1599
1488 sub { 1600 sub {
1489 # accept 1601 # accept
1490 if ($$rbuf =~ $accept) { 1602 if ($$rbuf =~ $accept) {
1491 $data .= substr $$rbuf, 0, $+[0], ""; 1603 $data .= substr $$rbuf, 0, $+[0], "";
1492 $cb->($self, $data); 1604 $cb->($_[0], $data);
1493 return 1; 1605 return 1;
1494 } 1606 }
1495 1607
1496 # reject 1608 # reject
1497 if ($reject && $$rbuf =~ $reject) { 1609 if ($reject && $$rbuf =~ $reject) {
1498 $self->_error (Errno::EBADMSG); 1610 $_[0]->_error (Errno::EBADMSG);
1499 } 1611 }
1500 1612
1501 # skip 1613 # skip
1502 if ($skip && $$rbuf =~ $skip) { 1614 if ($skip && $$rbuf =~ $skip) {
1503 $data .= substr $$rbuf, 0, $+[0], ""; 1615 $data .= substr $$rbuf, 0, $+[0], "";
… …
1519 my ($self, $cb) = @_; 1631 my ($self, $cb) = @_;
1520 1632
1521 sub { 1633 sub {
1522 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) { 1634 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) {
1523 if ($_[0]{rbuf} =~ /[^0-9]/) { 1635 if ($_[0]{rbuf} =~ /[^0-9]/) {
1524 $self->_error (Errno::EBADMSG); 1636 $_[0]->_error (Errno::EBADMSG);
1525 } 1637 }
1526 return; 1638 return;
1527 } 1639 }
1528 1640
1529 my $len = $1; 1641 my $len = $1;
1530 1642
1531 $self->unshift_read (chunk => $len, sub { 1643 $_[0]->unshift_read (chunk => $len, sub {
1532 my $string = $_[1]; 1644 my $string = $_[1];
1533 $_[0]->unshift_read (chunk => 1, sub { 1645 $_[0]->unshift_read (chunk => 1, sub {
1534 if ($_[1] eq ",") { 1646 if ($_[1] eq ",") {
1535 $cb->($_[0], $string); 1647 $cb->($_[0], $string);
1536 } else { 1648 } else {
1537 $self->_error (Errno::EBADMSG); 1649 $_[0]->_error (Errno::EBADMSG);
1538 } 1650 }
1539 }); 1651 });
1540 }); 1652 });
1541 1653
1542 1 1654 1
… …
1592=item json => $cb->($handle, $hash_or_arrayref) 1704=item json => $cb->($handle, $hash_or_arrayref)
1593 1705
1594Reads a JSON object or array, decodes it and passes it to the 1706Reads a JSON object or array, decodes it and passes it to the
1595callback. When a parse error occurs, an C<EBADMSG> error will be raised. 1707callback. When a parse error occurs, an C<EBADMSG> error will be raised.
1596 1708
1597If a C<json> object was passed to the constructor, then that will be used 1709If a C<json> object was passed to the constructor, then that will be
1598for the final decode, otherwise it will create a JSON coder expecting UTF-8. 1710used for the final decode, otherwise it will create a L<JSON::XS> or
1711L<JSON::PP> coder object expecting UTF-8.
1599 1712
1600This read type uses the incremental parser available with JSON version 1713This read type uses the incremental parser available with JSON version
16012.09 (and JSON::XS version 2.2) and above. You have to provide a 17142.09 (and JSON::XS version 2.2) and above.
1602dependency on your own: this module will load the JSON module, but
1603AnyEvent does not depend on it itself.
1604 1715
1605Since JSON texts are fully self-delimiting, the C<json> read and write 1716Since JSON texts are fully self-delimiting, the C<json> read and write
1606types are an ideal simple RPC protocol: just exchange JSON datagrams. See 1717types are an ideal simple RPC protocol: just exchange JSON datagrams. See
1607the C<json> write type description, above, for an actual example. 1718the C<json> write type description, above, for an actual example.
1608 1719
… …
1612 my ($self, $cb) = @_; 1723 my ($self, $cb) = @_;
1613 1724
1614 my $json = $self->{json} ||= json_coder; 1725 my $json = $self->{json} ||= json_coder;
1615 1726
1616 my $data; 1727 my $data;
1617 my $rbuf = \$self->{rbuf};
1618 1728
1619 sub { 1729 sub {
1620 my $ref = eval { $json->incr_parse ($self->{rbuf}) }; 1730 my $ref = eval { $json->incr_parse ($_[0]{rbuf}) };
1621 1731
1622 if ($ref) { 1732 if ($ref) {
1623 $self->{rbuf} = $json->incr_text; 1733 $_[0]{rbuf} = $json->incr_text;
1624 $json->incr_text = ""; 1734 $json->incr_text = "";
1625 $cb->($self, $ref); 1735 $cb->($_[0], $ref);
1626 1736
1627 1 1737 1
1628 } elsif ($@) { 1738 } elsif ($@) {
1629 # error case 1739 # error case
1630 $json->incr_skip; 1740 $json->incr_skip;
1631 1741
1632 $self->{rbuf} = $json->incr_text; 1742 $_[0]{rbuf} = $json->incr_text;
1633 $json->incr_text = ""; 1743 $json->incr_text = "";
1634 1744
1635 $self->_error (Errno::EBADMSG); 1745 $_[0]->_error (Errno::EBADMSG);
1636 1746
1637 () 1747 ()
1638 } else { 1748 } else {
1639 $self->{rbuf} = ""; 1749 $_[0]{rbuf} = "";
1640 1750
1751 ()
1752 }
1753 }
1754};
1755
1756=item cbor => $cb->($handle, $scalar)
1757
1758Reads a CBOR value, decodes it and passes it to the callback. When a parse
1759error occurs, an C<EBADMSG> error will be raised.
1760
1761If a L<CBOR::XS> object was passed to the constructor, then that will be
1762used for the final decode, otherwise it will create a CBOR coder without
1763enabling any options.
1764
1765You have to provide a dependency to L<CBOR::XS> on your own: this module
1766will load the L<CBOR::XS> module, but AnyEvent does not depend on it
1767itself.
1768
1769Since CBOR values are fully self-delimiting, the C<cbor> read and write
1770types are an ideal simple RPC protocol: just exchange CBOR datagrams. See
1771the C<cbor> write type description, above, for an actual example.
1772
1773=cut
1774
1775register_read_type cbor => sub {
1776 my ($self, $cb) = @_;
1777
1778 my $cbor = $self->{cbor} ||= cbor_coder;
1779
1780 my $data;
1781
1782 sub {
1783 my (@value) = eval { $cbor->incr_parse ($_[0]{rbuf}) };
1784
1785 if (@value) {
1786 $cb->($_[0], @value);
1787
1788 1
1789 } elsif ($@) {
1790 # error case
1791 $cbor->incr_reset;
1792
1793 $_[0]->_error (Errno::EBADMSG);
1794
1795 ()
1796 } else {
1641 () 1797 ()
1642 } 1798 }
1643 } 1799 }
1644}; 1800};
1645 1801
… …
1654=cut 1810=cut
1655 1811
1656register_read_type storable => sub { 1812register_read_type storable => sub {
1657 my ($self, $cb) = @_; 1813 my ($self, $cb) = @_;
1658 1814
1659 require Storable; 1815 require Storable unless $Storable::VERSION;
1660 1816
1661 sub { 1817 sub {
1662 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method 1818 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method
1663 defined (my $len = eval { unpack "w", $_[0]{rbuf} }) 1819 defined (my $len = eval { unpack "w", $_[0]{rbuf} })
1664 or return; 1820 or return;
… …
1667 1823
1668 # bypass unshift if we already have the remaining chunk 1824 # bypass unshift if we already have the remaining chunk
1669 if ($format + $len <= length $_[0]{rbuf}) { 1825 if ($format + $len <= length $_[0]{rbuf}) {
1670 my $data = substr $_[0]{rbuf}, $format, $len; 1826 my $data = substr $_[0]{rbuf}, $format, $len;
1671 substr $_[0]{rbuf}, 0, $format + $len, ""; 1827 substr $_[0]{rbuf}, 0, $format + $len, "";
1828
1672 $cb->($_[0], Storable::thaw ($data)); 1829 eval { $cb->($_[0], Storable::thaw ($data)); 1 }
1830 or return $_[0]->_error (Errno::EBADMSG);
1673 } else { 1831 } else {
1674 # remove prefix 1832 # remove prefix
1675 substr $_[0]{rbuf}, 0, $format, ""; 1833 substr $_[0]{rbuf}, 0, $format, "";
1676 1834
1677 # read remaining chunk 1835 # read remaining chunk
1678 $_[0]->unshift_read (chunk => $len, sub { 1836 $_[0]->unshift_read (chunk => $len, sub {
1679 if (my $ref = eval { Storable::thaw ($_[1]) }) { 1837 eval { $cb->($_[0], Storable::thaw ($_[1])); 1 }
1680 $cb->($_[0], $ref);
1681 } else {
1682 $self->_error (Errno::EBADMSG); 1838 or $_[0]->_error (Errno::EBADMSG);
1683 }
1684 }); 1839 });
1685 } 1840 }
1686 1841
1687 1 1842 1
1688 } 1843 }
1844};
1845
1846=item tls_detect => $cb->($handle, $detect, $major, $minor)
1847
1848Checks the input stream for a valid SSL or TLS handshake TLSPaintext
1849record without consuming anything. Only SSL version 3 or higher
1850is handled, up to the fictituous protocol 4.x (but both SSL3+ and
1851SSL2-compatible framing is supported).
1852
1853If it detects that the input data is likely TLS, it calls the callback
1854with a true value for C<$detect> and the (on-wire) TLS version as second
1855and third argument (C<$major> is C<3>, and C<$minor> is 0..3 for SSL
18563.0, TLS 1.0, 1.1 and 1.2, respectively). If it detects the input to
1857be definitely not TLS, it calls the callback with a false value for
1858C<$detect>.
1859
1860The callback could use this information to decide whether or not to start
1861TLS negotiation.
1862
1863In all cases the data read so far is passed to the following read
1864handlers.
1865
1866Usually you want to use the C<tls_autostart> read type instead.
1867
1868If you want to design a protocol that works in the presence of TLS
1869dtection, make sure that any non-TLS data doesn't start with the octet 22
1870(ASCII SYN, 16 hex) or 128-255 (i.e. highest bit set). The checks this
1871read type does are a bit more strict, but might losen in the future to
1872accomodate protocol changes.
1873
1874This read type does not rely on L<AnyEvent::TLS> (and thus, not on
1875L<Net::SSLeay>).
1876
1877=item tls_autostart => $tls[, $tls_ctx]
1878
1879Tries to detect a valid SSL or TLS handshake. If one is detected, it tries
1880to start tls by calling C<starttls> with the given arguments.
1881
1882In practise, C<$tls> must be C<accept>, or a Net::SSLeay context that has
1883been configured to accept, as servers do not normally send a handshake on
1884their own and ths cannot be detected in this way.
1885
1886See C<tls_detect> above for more details.
1887
1888Example: give the client a chance to start TLS before accepting a text
1889line.
1890
1891 $hdl->push_read (tls_detect => "accept");
1892 $hdl->push_read (line => sub {
1893 print "received ", ($_[0]{tls} ? "encrypted" : "cleartext"), " <$_[1]>\n";
1894 });
1895
1896=cut
1897
1898register_read_type tls_detect => sub {
1899 my ($self, $cb) = @_;
1900
1901 sub {
1902 # this regex matches a full or partial tls record
1903 if (
1904 # ssl3+: type(22=handshake) major(=3) minor(any) length_hi
1905 $self->{rbuf} =~ /^(?:\z| \x16 (\z| [\x03\x04] (?:\z| . (?:\z| [\x00-\x40] ))))/xs
1906 # ssl2 comapatible: len_hi len_lo type(1) major minor dummy(forlength)
1907 or $self->{rbuf} =~ /^(?:\z| [\x80-\xff] (?:\z| . (?:\z| \x01 (\z| [\x03\x04] (?:\z| . (?:\z| . ))))))/xs
1908 ) {
1909 return if 3 != length $1; # partial match, can't decide yet
1910
1911 # full match, valid TLS record
1912 my ($major, $minor) = unpack "CC", $1;
1913 $cb->($self, "accept", $major + $minor * 0.1);
1914 } else {
1915 # mismatch == guaranteed not TLS
1916 $cb->($self, undef);
1917 }
1918
1919 1
1920 }
1921};
1922
1923register_read_type tls_autostart => sub {
1924 my ($self, @tls) = @_;
1925
1926 $RH{tls_detect}($self, sub {
1927 return unless $_[1];
1928 $_[0]->starttls (@tls);
1929 })
1689}; 1930};
1690 1931
1691=back 1932=back
1692 1933
1693=item custom read types - Package::anyevent_read_type $handle, $cb, @args 1934=item custom read types - Package::anyevent_read_type $handle, $cb, @args
… …
1725Note that AnyEvent::Handle will automatically C<start_read> for you when 1966Note that AnyEvent::Handle will automatically C<start_read> for you when
1726you change the C<on_read> callback or push/unshift a read callback, and it 1967you change the C<on_read> callback or push/unshift a read callback, and it
1727will automatically C<stop_read> for you when neither C<on_read> is set nor 1968will automatically C<stop_read> for you when neither C<on_read> is set nor
1728there are any read requests in the queue. 1969there are any read requests in the queue.
1729 1970
1730These methods will have no effect when in TLS mode (as TLS doesn't support 1971In older versions of this module (<= 5.3), these methods had no effect,
1731half-duplex connections). 1972as TLS does not support half-duplex connections. In current versions they
1973work as expected, as this behaviour is required to avoid certain resource
1974attacks, where the program would be forced to read (and buffer) arbitrary
1975amounts of data before being able to send some data. The drawback is that
1976some readings of the the SSL/TLS specifications basically require this
1977attack to be working, as SSL/TLS implementations might stall sending data
1978during a rehandshake.
1979
1980As a guideline, during the initial handshake, you should not stop reading,
1981and as a client, it might cause problems, depending on your application.
1732 1982
1733=cut 1983=cut
1734 1984
1735sub stop_read { 1985sub stop_read {
1736 my ($self) = @_; 1986 my ($self) = @_;
1737 1987
1738 delete $self->{_rw} unless $self->{tls}; 1988 delete $self->{_rw};
1739} 1989}
1740 1990
1741sub start_read { 1991sub start_read {
1742 my ($self) = @_; 1992 my ($self) = @_;
1743 1993
1744 unless ($self->{_rw} || $self->{_eof} || !$self->{fh}) { 1994 unless ($self->{_rw} || $self->{_eof} || !$self->{fh}) {
1745 Scalar::Util::weaken $self; 1995 Scalar::Util::weaken $self;
1746 1996
1747 $self->{_rw} = AE::io $self->{fh}, 0, sub { 1997 $self->{_rw} = AE::io $self->{fh}, 0, sub {
1748 my $rbuf = \($self->{tls} ? my $buf : $self->{rbuf}); 1998 my $rbuf = \($self->{tls} ? my $buf : $self->{rbuf});
1749 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf; 1999 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size}, length $$rbuf;
1750 2000
1751 if ($len > 0) { 2001 if ($len > 0) {
1752 $self->{_activity} = $self->{_ractivity} = AE::now; 2002 $self->{_activity} = $self->{_ractivity} = AE::now;
1753 2003
1754 if ($self->{tls}) { 2004 if ($self->{tls}) {
… …
1757 &_dotls ($self); 2007 &_dotls ($self);
1758 } else { 2008 } else {
1759 $self->_drain_rbuf; 2009 $self->_drain_rbuf;
1760 } 2010 }
1761 2011
2012 if ($len == $self->{read_size}) {
2013 $self->{read_size} *= 2;
2014 $self->{read_size} = $self->{max_read_size} || MAX_READ_SIZE
2015 if $self->{read_size} > ($self->{max_read_size} || MAX_READ_SIZE);
2016 }
2017
1762 } elsif (defined $len) { 2018 } elsif (defined $len) {
1763 delete $self->{_rw}; 2019 delete $self->{_rw};
1764 $self->{_eof} = 1; 2020 $self->{_eof} = 1;
1765 $self->_drain_rbuf; 2021 $self->_drain_rbuf;
1766 2022
… …
1778 my ($self, $err) = @_; 2034 my ($self, $err) = @_;
1779 2035
1780 return $self->_error ($!, 1) 2036 return $self->_error ($!, 1)
1781 if $err == Net::SSLeay::ERROR_SYSCALL (); 2037 if $err == Net::SSLeay::ERROR_SYSCALL ();
1782 2038
1783 my $err =Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ()); 2039 my $err = Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ());
1784 2040
1785 # reduce error string to look less scary 2041 # reduce error string to look less scary
1786 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /; 2042 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /;
1787 2043
1788 if ($self->{_on_starttls}) { 2044 if ($self->{_on_starttls}) {
… …
1802sub _dotls { 2058sub _dotls {
1803 my ($self) = @_; 2059 my ($self) = @_;
1804 2060
1805 my $tmp; 2061 my $tmp;
1806 2062
1807 if (length $self->{_tls_wbuf}) { 2063 while (length $self->{_tls_wbuf}) {
1808 while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) { 2064 if (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) <= 0) {
1809 substr $self->{_tls_wbuf}, 0, $tmp, ""; 2065 $tmp = Net::SSLeay::get_error ($self->{tls}, $tmp);
2066
2067 return $self->_tls_error ($tmp)
2068 if $tmp != $ERROR_WANT_READ
2069 && ($tmp != $ERROR_SYSCALL || $!);
2070
2071 last;
1810 } 2072 }
1811 2073
1812 $tmp = Net::SSLeay::get_error ($self->{tls}, $tmp); 2074 substr $self->{_tls_wbuf}, 0, $tmp, "";
1813 return $self->_tls_error ($tmp)
1814 if $tmp != $ERROR_WANT_READ
1815 && ($tmp != $ERROR_SYSCALL || $!);
1816 } 2075 }
1817 2076
1818 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) { 2077 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
1819 unless (length $tmp) { 2078 unless (length $tmp) {
1820 $self->{_on_starttls} 2079 $self->{_on_starttls}
… …
1834 $self->{_tls_rbuf} .= $tmp; 2093 $self->{_tls_rbuf} .= $tmp;
1835 $self->_drain_rbuf; 2094 $self->_drain_rbuf;
1836 $self->{tls} or return; # tls session might have gone away in callback 2095 $self->{tls} or return; # tls session might have gone away in callback
1837 } 2096 }
1838 2097
1839 $tmp = Net::SSLeay::get_error ($self->{tls}, -1); 2098 $tmp = Net::SSLeay::get_error ($self->{tls}, -1); # -1 is not neccessarily correct, but Net::SSLeay doesn't tell us
1840 return $self->_tls_error ($tmp) 2099 return $self->_tls_error ($tmp)
1841 if $tmp != $ERROR_WANT_READ 2100 if $tmp != $ERROR_WANT_READ
1842 && ($tmp != $ERROR_SYSCALL || $!); 2101 && ($tmp != $ERROR_SYSCALL || $!);
1843 2102
1844 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) { 2103 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {
… …
1854 2113
1855=item $handle->starttls ($tls[, $tls_ctx]) 2114=item $handle->starttls ($tls[, $tls_ctx])
1856 2115
1857Instead of starting TLS negotiation immediately when the AnyEvent::Handle 2116Instead of starting TLS negotiation immediately when the AnyEvent::Handle
1858object is created, you can also do that at a later time by calling 2117object is created, you can also do that at a later time by calling
1859C<starttls>. 2118C<starttls>. See the C<tls> constructor argument for general info.
1860 2119
1861Starting TLS is currently an asynchronous operation - when you push some 2120Starting TLS is currently an asynchronous operation - when you push some
1862write data and then call C<< ->starttls >> then TLS negotiation will start 2121write data and then call C<< ->starttls >> then TLS negotiation will start
1863immediately, after which the queued write data is then sent. 2122immediately, after which the queued write data is then sent. This might
2123change in future versions, so best make sure you have no outstanding write
2124data when calling this method.
1864 2125
1865The first argument is the same as the C<tls> constructor argument (either 2126The first argument is the same as the C<tls> constructor argument (either
1866C<"connect">, C<"accept"> or an existing Net::SSLeay object). 2127C<"connect">, C<"accept"> or an existing Net::SSLeay object).
1867 2128
1868The second argument is the optional C<AnyEvent::TLS> object that is used 2129The second argument is the optional C<AnyEvent::TLS> object that is used
… …
1874context in C<< $handle->{tls_ctx} >> after this call and can be used or 2135context in C<< $handle->{tls_ctx} >> after this call and can be used or
1875changed to your liking. Note that the handshake might have already started 2136changed to your liking. Note that the handshake might have already started
1876when this function returns. 2137when this function returns.
1877 2138
1878Due to bugs in OpenSSL, it might or might not be possible to do multiple 2139Due to bugs in OpenSSL, it might or might not be possible to do multiple
1879handshakes on the same stream. Best do not attempt to use the stream after 2140handshakes on the same stream. It is best to not attempt to use the
1880stopping TLS. 2141stream after stopping TLS.
1881 2142
1882This method may invoke callbacks (and therefore the handle might be 2143This method may invoke callbacks (and therefore the handle might be
1883destroyed after it returns). 2144destroyed after it returns).
1884 2145
1885=cut 2146=cut
… …
1890 my ($self, $tls, $ctx) = @_; 2151 my ($self, $tls, $ctx) = @_;
1891 2152
1892 Carp::croak "It is an error to call starttls on an AnyEvent::Handle object while TLS is already active, caught" 2153 Carp::croak "It is an error to call starttls on an AnyEvent::Handle object while TLS is already active, caught"
1893 if $self->{tls}; 2154 if $self->{tls};
1894 2155
2156 unless (defined $AnyEvent::TLS::VERSION) {
2157 eval {
2158 require Net::SSLeay;
2159 require AnyEvent::TLS;
2160 1
2161 } or return $self->_error (Errno::EPROTO, 1, "TLS support not available on this system");
2162 }
2163
1895 $self->{tls} = $tls; 2164 $self->{tls} = $tls;
1896 $self->{tls_ctx} = $ctx if @_ > 2; 2165 $self->{tls_ctx} = $ctx if @_ > 2;
1897 2166
1898 return unless $self->{fh}; 2167 return unless $self->{fh};
1899 2168
1900 require Net::SSLeay;
1901
1902 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL (); 2169 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL ();
1903 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ (); 2170 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ ();
1904 2171
1905 $tls = delete $self->{tls}; 2172 $tls = delete $self->{tls};
1906 $ctx = $self->{tls_ctx}; 2173 $ctx = $self->{tls_ctx};
1907 2174
1908 local $Carp::CarpLevel = 1; # skip ourselves when creating a new context or session 2175 local $Carp::CarpLevel = 1; # skip ourselves when creating a new context or session
1909 2176
1910 if ("HASH" eq ref $ctx) { 2177 if ("HASH" eq ref $ctx) {
1911 require AnyEvent::TLS;
1912
1913 if ($ctx->{cache}) { 2178 if ($ctx->{cache}) {
1914 my $key = $ctx+0; 2179 my $key = $ctx+0;
1915 $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx; 2180 $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx;
1916 } else { 2181 } else {
1917 $ctx = new AnyEvent::TLS %$ctx; 2182 $ctx = new AnyEvent::TLS %$ctx;
… …
1939 Net::SSLeay::CTX_set_mode ($tls, 1|2); 2204 Net::SSLeay::CTX_set_mode ($tls, 1|2);
1940 2205
1941 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 2206 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1942 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 2207 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1943 2208
1944 Net::SSLeay::BIO_write ($self->{_rbio}, delete $self->{rbuf}); 2209 Net::SSLeay::BIO_write ($self->{_rbio}, $self->{rbuf});
2210 $self->{rbuf} = "";
1945 2211
1946 Net::SSLeay::set_bio ($tls, $self->{_rbio}, $self->{_wbio}); 2212 Net::SSLeay::set_bio ($tls, $self->{_rbio}, $self->{_wbio});
1947 2213
1948 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) } 2214 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) }
1949 if $self->{on_starttls}; 2215 if $self->{on_starttls};
… …
1987 if $self->{tls} > 0; 2253 if $self->{tls} > 0;
1988 2254
1989 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)}; 2255 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)};
1990} 2256}
1991 2257
2258=item $handle->resettls
2259
2260This rarely-used method simply resets and TLS state on the handle, usually
2261causing data loss.
2262
2263One case where it may be useful is when you want to skip over the data in
2264the stream but you are not interested in interpreting it, so data loss is
2265no concern.
2266
2267=cut
2268
2269*resettls = \&_freetls;
2270
1992sub DESTROY { 2271sub DESTROY {
1993 my ($self) = @_; 2272 my ($self) = @_;
1994 2273
1995 &_freetls; 2274 &_freetls;
1996 2275
… …
2005 push @linger, AE::io $fh, 1, sub { 2284 push @linger, AE::io $fh, 1, sub {
2006 my $len = syswrite $fh, $wbuf, length $wbuf; 2285 my $len = syswrite $fh, $wbuf, length $wbuf;
2007 2286
2008 if ($len > 0) { 2287 if ($len > 0) {
2009 substr $wbuf, 0, $len, ""; 2288 substr $wbuf, 0, $len, "";
2010 } else { 2289 } elsif (defined $len || ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK)) {
2011 @linger = (); # end 2290 @linger = (); # end
2012 } 2291 }
2013 }; 2292 };
2014 push @linger, AE::timer $linger, 0, sub { 2293 push @linger, AE::timer $linger, 0, sub {
2015 @linger = (); 2294 @linger = ();
… …
2111 2390
2112It is only safe to "forget" the reference inside EOF or error callbacks, 2391It is only safe to "forget" the reference inside EOF or error callbacks,
2113from within all other callbacks, you need to explicitly call the C<< 2392from within all other callbacks, you need to explicitly call the C<<
2114->destroy >> method. 2393->destroy >> method.
2115 2394
2395=item Why is my C<on_eof> callback never called?
2396
2397Probably because your C<on_error> callback is being called instead: When
2398you have outstanding requests in your read queue, then an EOF is
2399considered an error as you clearly expected some data.
2400
2401To avoid this, make sure you have an empty read queue whenever your handle
2402is supposed to be "idle" (i.e. connection closes are O.K.). You can set
2403an C<on_read> handler that simply pushes the first read requests in the
2404queue.
2405
2406See also the next question, which explains this in a bit more detail.
2407
2408=item How can I serve requests in a loop?
2409
2410Most protocols consist of some setup phase (authentication for example)
2411followed by a request handling phase, where the server waits for requests
2412and handles them, in a loop.
2413
2414There are two important variants: The first (traditional, better) variant
2415handles requests until the server gets some QUIT command, causing it to
2416close the connection first (highly desirable for a busy TCP server). A
2417client dropping the connection is an error, which means this variant can
2418detect an unexpected detection close.
2419
2420To handle this case, always make sure you have a non-empty read queue, by
2421pushing the "read request start" handler on it:
2422
2423 # we assume a request starts with a single line
2424 my @start_request; @start_request = (line => sub {
2425 my ($hdl, $line) = @_;
2426
2427 ... handle request
2428
2429 # push next request read, possibly from a nested callback
2430 $hdl->push_read (@start_request);
2431 });
2432
2433 # auth done, now go into request handling loop
2434 # now push the first @start_request
2435 $hdl->push_read (@start_request);
2436
2437By always having an outstanding C<push_read>, the handle always expects
2438some data and raises the C<EPIPE> error when the connction is dropped
2439unexpectedly.
2440
2441The second variant is a protocol where the client can drop the connection
2442at any time. For TCP, this means that the server machine may run out of
2443sockets easier, and in general, it means you cannot distinguish a protocl
2444failure/client crash from a normal connection close. Nevertheless, these
2445kinds of protocols are common (and sometimes even the best solution to the
2446problem).
2447
2448Having an outstanding read request at all times is possible if you ignore
2449C<EPIPE> errors, but this doesn't help with when the client drops the
2450connection during a request, which would still be an error.
2451
2452A better solution is to push the initial request read in an C<on_read>
2453callback. This avoids an error, as when the server doesn't expect data
2454(i.e. is idly waiting for the next request, an EOF will not raise an
2455error, but simply result in an C<on_eof> callback. It is also a bit slower
2456and simpler:
2457
2458 # auth done, now go into request handling loop
2459 $hdl->on_read (sub {
2460 my ($hdl) = @_;
2461
2462 # called each time we receive data but the read queue is empty
2463 # simply start read the request
2464
2465 $hdl->push_read (line => sub {
2466 my ($hdl, $line) = @_;
2467
2468 ... handle request
2469
2470 # do nothing special when the request has been handled, just
2471 # let the request queue go empty.
2472 });
2473 });
2474
2116=item I get different callback invocations in TLS mode/Why can't I pause 2475=item I get different callback invocations in TLS mode/Why can't I pause
2117reading? 2476reading?
2118 2477
2119Unlike, say, TCP, TLS connections do not consist of two independent 2478Unlike, say, TCP, TLS connections do not consist of two independent
2120communication channels, one for each direction. Or put differently. The 2479communication channels, one for each direction. Or put differently, the
2121read and write directions are not independent of each other: you cannot 2480read and write directions are not independent of each other: you cannot
2122write data unless you are also prepared to read, and vice versa. 2481write data unless you are also prepared to read, and vice versa.
2123 2482
2124This can mean than, in TLS mode, you might get C<on_error> or C<on_eof> 2483This means that, in TLS mode, you might get C<on_error> or C<on_eof>
2125callback invocations when you are not expecting any read data - the reason 2484callback invocations when you are not expecting any read data - the reason
2126is that AnyEvent::Handle always reads in TLS mode. 2485is that AnyEvent::Handle always reads in TLS mode.
2127 2486
2128During the connection, you have to make sure that you always have a 2487During the connection, you have to make sure that you always have a
2129non-empty read-queue, or an C<on_read> watcher. At the end of the 2488non-empty read-queue, or an C<on_read> watcher. At the end of the
… …
2141 $handle->on_eof (undef); 2500 $handle->on_eof (undef);
2142 $handle->on_error (sub { 2501 $handle->on_error (sub {
2143 my $data = delete $_[0]{rbuf}; 2502 my $data = delete $_[0]{rbuf};
2144 }); 2503 });
2145 2504
2505Note that this example removes the C<rbuf> member from the handle object,
2506which is not normally allowed by the API. It is expressly permitted in
2507this case only, as the handle object needs to be destroyed afterwards.
2508
2146The reason to use C<on_error> is that TCP connections, due to latencies 2509The reason to use C<on_error> is that TCP connections, due to latencies
2147and packets loss, might get closed quite violently with an error, when in 2510and packets loss, might get closed quite violently with an error, when in
2148fact, all data has been received. 2511fact all data has been received.
2149 2512
2150It is usually better to use acknowledgements when transferring data, 2513It is usually better to use acknowledgements when transferring data,
2151to make sure the other side hasn't just died and you got the data 2514to make sure the other side hasn't just died and you got the data
2152intact. This is also one reason why so many internet protocols have an 2515intact. This is also one reason why so many internet protocols have an
2153explicit QUIT command. 2516explicit QUIT command.
… …
2160C<low_water_mark> this will be called precisely when all data has been 2523C<low_water_mark> this will be called precisely when all data has been
2161written to the socket: 2524written to the socket:
2162 2525
2163 $handle->push_write (...); 2526 $handle->push_write (...);
2164 $handle->on_drain (sub { 2527 $handle->on_drain (sub {
2165 warn "all data submitted to the kernel\n"; 2528 AE::log debug => "All data submitted to the kernel.";
2166 undef $handle; 2529 undef $handle;
2167 }); 2530 });
2168 2531
2169If you just want to queue some data and then signal EOF to the other side, 2532If you just want to queue some data and then signal EOF to the other side,
2170consider using C<< ->push_shutdown >> instead. 2533consider using C<< ->push_shutdown >> instead.
2171 2534
2172=item I want to contact a TLS/SSL server, I don't care about security. 2535=item I want to contact a TLS/SSL server, I don't care about security.
2173 2536
2174If your TLS server is a pure TLS server (e.g. HTTPS) that only speaks TLS, 2537If your TLS server is a pure TLS server (e.g. HTTPS) that only speaks TLS,
2175simply connect to it and then create the AnyEvent::Handle with the C<tls> 2538connect to it and then create the AnyEvent::Handle with the C<tls>
2176parameter: 2539parameter:
2177 2540
2178 tcp_connect $host, $port, sub { 2541 tcp_connect $host, $port, sub {
2179 my ($fh) = @_; 2542 my ($fh) = @_;
2180 2543
… …
2254When you have intermediate CA certificates that your clients might not 2617When you have intermediate CA certificates that your clients might not
2255know about, just append them to the C<cert_file>. 2618know about, just append them to the C<cert_file>.
2256 2619
2257=back 2620=back
2258 2621
2259
2260=head1 SUBCLASSING AnyEvent::Handle 2622=head1 SUBCLASSING AnyEvent::Handle
2261 2623
2262In many cases, you might want to subclass AnyEvent::Handle. 2624In many cases, you might want to subclass AnyEvent::Handle.
2263 2625
2264To make this easier, a given version of AnyEvent::Handle uses these 2626To make this easier, a given version of AnyEvent::Handle uses these
… …
2280 2642
2281=item * all members not documented here and not prefixed with an underscore 2643=item * all members not documented here and not prefixed with an underscore
2282are free to use in subclasses. 2644are free to use in subclasses.
2283 2645
2284Of course, new versions of AnyEvent::Handle may introduce more "public" 2646Of course, new versions of AnyEvent::Handle may introduce more "public"
2285member variables, but thats just life, at least it is documented. 2647member variables, but that's just life. At least it is documented.
2286 2648
2287=back 2649=back
2288 2650
2289=head1 AUTHOR 2651=head1 AUTHOR
2290 2652
2291Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>. 2653Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>.
2292 2654
2293=cut 2655=cut
2294 2656
22951; # End of AnyEvent::Handle 26571
2658

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines