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.193 by root, Mon Mar 15 18:51:30 2010 UTC vs.
Revision 1.238 by root, Tue Dec 10 15:54:51 2013 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent 3AnyEvent::Handle - non-blocking I/O on streaming handles via AnyEvent
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use AnyEvent; 7 use AnyEvent;
8 use AnyEvent::Handle; 8 use AnyEvent::Handle;
… …
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
36filehandles. 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
… …
192To access (and remove data from) the read buffer, use the C<< ->rbuf >> 205To access (and remove data from) the read buffer, use the C<< ->rbuf >>
193method or access the C<< $handle->{rbuf} >> member directly. Note that you 206method or access the C<< $handle->{rbuf} >> member directly. Note that you
194must not enlarge or modify the read buffer, you can only remove data at 207must not enlarge or modify the read buffer, you can only remove data at
195the beginning from it. 208the beginning from it.
196 209
210You can also call C<< ->push_read (...) >> or any other function that
211modifies the read queue. Or do both. Or ...
212
197When an EOF condition is detected then AnyEvent::Handle will first try to 213When an EOF condition is detected, AnyEvent::Handle will first try to
198feed 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
199calling 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
200error will be raised (with C<$!> set to C<EPIPE>). 216error will be raised (with C<$!> set to C<EPIPE>).
201 217
202Note 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
… …
220If 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
221set, 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>.
222 238
223=item on_drain => $cb->($handle) 239=item on_drain => $cb->($handle)
224 240
225This 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
226(or when the callback is set and the buffer is empty already). 242empty (and immediately when the handle object is created).
227 243
228To append to the write buffer, use the C<< ->push_write >> method. 244To append to the write buffer, use the C<< ->push_write >> method.
229 245
230This 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
231into 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
… …
243many seconds pass without a successful read or write on the underlying 259many seconds pass without a successful read or write on the underlying
244file 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
245will 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>
246error will be raised). 262error will be raised).
247 263
248There are three variants of the timeouts that work fully independent 264There are three variants of the timeouts that work independently of each
249of 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:
250C<timeout>, C<rtimeout> and C<wtimeout>, with corresponding callbacks 267C<timeout>, C<rtimeout> and C<wtimeout>, with corresponding callbacks
251C<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
252C<timeout_reset>, C<rtimeout_reset>, and C<wtimeout_reset>. 269C<timeout_reset>, C<rtimeout_reset>, and C<wtimeout_reset>.
253 270
254Note 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
255any outstanding read or write requests: If you plan to keep the connection 272outstanding read or write requests: If you plan to keep the connection
256idle then you should disable the timout temporarily or ignore the timeout 273idle then you should disable the timeout temporarily or ignore the
257in the C<on_timeout> callback, in which case AnyEvent::Handle will simply 274timeout in the corresponding C<on_timeout> callback, in which case
258restart the timeout. 275AnyEvent::Handle will simply restart the timeout.
259 276
260Zero (the default) disables this timeout. 277Zero (the default) disables the corresponding timeout.
261 278
262=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)
263 284
264Called whenever the inactivity timeout passes. If you return from this 285Called whenever the inactivity timeout passes. If you return from this
265callback, 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,
266so this condition is not fatal in any way. 287so this condition is not fatal in any way.
267 288
… …
275be 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
276(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
277amount 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
278isn't finished). 299isn't finished).
279 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
280=item autocork => <boolean> 316=item autocork => <boolean>
281 317
282When disabled (the default), then C<push_write> will try to immediately 318When disabled (the default), C<push_write> will try to immediately
283write 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
284a 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
285be inefficient if you write multiple small chunks (on the wire, this 321be inefficient if you write multiple small chunks (on the wire, this
286disadvantage is usually avoided by your kernel's nagle algorithm, see 322disadvantage is usually avoided by your kernel's nagle algorithm, see
287C<no_delay>, but this option can save costly syscalls). 323C<no_delay>, but this option can save costly syscalls).
288 324
289When enabled, then writes will always be queued till the next event loop 325When enabled, writes will always be queued till the next event loop
290iteration. This is efficient when you do many small writes per iteration, 326iteration. This is efficient when you do many small writes per iteration,
291but 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
292the write buffer often is full). It also increases write latency. 328the write buffer often is full). It also increases write latency.
293 329
294=item no_delay => <boolean> 330=item no_delay => <boolean>
… …
298the Nagle algorithm, and usually it is beneficial. 334the Nagle algorithm, and usually it is beneficial.
299 335
300In 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
301accomplishd by setting this option to a true value. 337accomplishd by setting this option to a true value.
302 338
303The default is your opertaing system's default behaviour (most likely 339The default is your operating system's default behaviour (most likely
304enabled), this option explicitly enables or disables it, if possible. 340enabled). This option explicitly enables or disables it, if possible.
305 341
306=item keepalive => <boolean> 342=item keepalive => <boolean>
307 343
308Enables (default disable) the SO_KEEPALIVE option on the stream socket: 344Enables (default disable) the SO_KEEPALIVE option on the stream socket:
309normally, TCP connections have no time-out once established, so TCP 345normally, TCP connections have no time-out once established, so TCP
310connections, once established, can stay alive forever even when the other 346connections, once established, can stay alive forever even when the other
311side 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
312TCP connections whent he other side becomes unreachable. While the default 348TCP connections when the other side becomes unreachable. While the default
313is OS-dependent, TCP keepalives usually kick in after around two hours, 349is OS-dependent, TCP keepalives usually kick in after around two hours,
314and, 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
315to 15 minutes later. 351to 15 minutes later.
316 352
317It 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
… …
335already 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
336from most attacks. 372from most attacks.
337 373
338=item read_size => <bytes> 374=item read_size => <bytes>
339 375
340The default read block size (the amount of bytes this module will 376The initial read block size, the number of bytes this module will try
341try to read during each loop iteration, which affects memory 377to read during each loop iteration. Each handle object will consume
342requirements). 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.
343 388
344=item low_water_mark => <bytes> 389=item low_water_mark => <bytes>
345 390
346Sets 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
347buffer: 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
348considered empty. 393considered empty.
349 394
350Sometimes it can be beneficial (for performance reasons) to add data to 395Sometimes it can be beneficial (for performance reasons) to add data to
351the 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
352the operating system kernel usually buffers data as well, so the default 397the operating system kernel usually buffers data as well, so the default
353is good in almost all cases. 398is good in almost all cases.
354 399
355=item linger => <seconds> 400=item linger => <seconds>
356 401
357If non-zero (default: C<3600>), then the destructor of the 402If this is non-zero (default: C<3600>), the destructor of the
358AnyEvent::Handle object will check whether there is still outstanding 403AnyEvent::Handle object will check whether there is still outstanding
359write 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
360socket. No errors will be reported (this mostly matches how the operating 405socket. No errors will be reported (this mostly matches how the operating
361system treats outstanding data at socket close time). 406system treats outstanding data at socket close time).
362 407
… …
369A string used to identify the remote site - usually the DNS hostname 414A string used to identify the remote site - usually the DNS hostname
370(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.
371 416
372Apart 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
373peername verification (see C<verify_peername> in L<AnyEvent::TLS>). This 418peername verification (see C<verify_peername> in L<AnyEvent::TLS>). This
374verification will be skipped when C<peername> is not specified or 419verification will be skipped when C<peername> is not specified or is
375C<undef>. 420C<undef>.
376 421
377=item tls => "accept" | "connect" | Net::SSLeay::SSL object 422=item tls => "accept" | "connect" | Net::SSLeay::SSL object
378 423
379When this parameter is given, it enables TLS (SSL) mode, that means 424When this parameter is given, it enables TLS (SSL) mode, that means
… …
384appropriate error message. 429appropriate error message.
385 430
386TLS mode requires Net::SSLeay to be installed (it will be loaded 431TLS mode requires Net::SSLeay to be installed (it will be loaded
387automatically 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
388have 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
389to 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.
390 436
391Unlike 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
392C<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>
393mode. 439mode.
394 440
… …
405B<IMPORTANT:> since Net::SSLeay "objects" are really only integers, 451B<IMPORTANT:> since Net::SSLeay "objects" are really only integers,
406passing 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
407happens 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
408segmentation fault. 454segmentation fault.
409 455
410See 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.
411 457
412=item tls_ctx => $anyevent_tls 458=item tls_ctx => $anyevent_tls
413 459
414Use 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
415(unless a connection object was specified directly). If this parameter is 461(unless a connection object was specified directly). If this
416missing, 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>.
417 464
418Instead 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
419=> 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
420new TLS context object. 467new TLS context object.
421 468
… …
430 477
431TLS 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
432callback 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>.
433 480
434Without this callback, handshake failures lead to C<on_error> being 481Without this callback, handshake failures lead to C<on_error> being
435called, as normal. 482called as usual.
436 483
437Note 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
438need 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
439then call C<< ->starttls >> again. 486then call C<< ->starttls >> again.
440 487
441=item on_stoptls => $cb->($handle) 488=item on_stoptls => $cb->($handle)
442 489
… …
449callback. 496callback.
450 497
451This callback will only be called on TLS shutdowns, not when the 498This callback will only be called on TLS shutdowns, not when the
452underlying handle signals EOF. 499underlying handle signals EOF.
453 500
454=item json => JSON or JSON::XS object 501=item json => L<JSON> or L<JSON::XS> object
455 502
456This 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.
457 504
458If 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
459suitable 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
460texts. 507texts.
461 508
462Note that you are responsible to depend on the JSON module if you want to 509Note that you are responsible to depend on the L<JSON> module if you want
463use this functionality, as AnyEvent does not have a dependency itself. 510to use this functionality, as AnyEvent does not have a dependency on it
511itself.
512
513=item cbor => L<CBOR::XS> object
514
515This is the cbor coder object used by the C<cbor> read and write types.
516
517If you don't supply it, then AnyEvent::Handle will create and use a
518suitable one (on demand), which will write CBOR without using extensions,
519if possible. texts.
520
521Note that you are responsible to depend on the L<CBOR::XS> module if you
522want to use this functionality, as AnyEvent does not have a dependency on
523it itself.
464 524
465=back 525=back
466 526
467=cut 527=cut
468 528
… …
490 $self->{connect}[0], 550 $self->{connect}[0],
491 $self->{connect}[1], 551 $self->{connect}[1],
492 sub { 552 sub {
493 my ($fh, $host, $port, $retry) = @_; 553 my ($fh, $host, $port, $retry) = @_;
494 554
555 delete $self->{_connect}; # no longer needed
556
495 if ($fh) { 557 if ($fh) {
496 $self->{fh} = $fh; 558 $self->{fh} = $fh;
497 559
498 delete $self->{_skip_drain_rbuf}; 560 delete $self->{_skip_drain_rbuf};
499 $self->_start; 561 $self->_start;
… …
506 }); 568 });
507 569
508 } else { 570 } else {
509 if ($self->{on_connect_error}) { 571 if ($self->{on_connect_error}) {
510 $self->{on_connect_error}($self, "$!"); 572 $self->{on_connect_error}($self, "$!");
511 $self->destroy; 573 $self->destroy if $self;
512 } else { 574 } else {
513 $self->_error ($!, 1); 575 $self->_error ($!, 1);
514 } 576 }
515 } 577 }
516 }, 578 },
517 sub { 579 sub {
518 local $self->{fh} = $_[0]; 580 local $self->{fh} = $_[0];
519 581
520 $self->{on_prepare} 582 $self->{on_prepare}
521 ? $self->{on_prepare}->($self) 583 ? $self->{on_prepare}->($self)
522 : () 584 : ()
523 } 585 }
524 ); 586 );
525 } 587 }
526 588
… …
532} 594}
533 595
534sub _start { 596sub _start {
535 my ($self) = @_; 597 my ($self) = @_;
536 598
599 # too many clueless people try to use udp and similar sockets
600 # with AnyEvent::Handle, do them a favour.
601 my $type = getsockopt $self->{fh}, Socket::SOL_SOCKET (), Socket::SO_TYPE ();
602 Carp::croak "AnyEvent::Handle: only stream sockets supported, anything else will NOT work!"
603 if Socket::SOCK_STREAM () != (unpack "I", $type) && defined $type;
604
537 AnyEvent::Util::fh_nonblocking $self->{fh}, 1; 605 AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
538 606
539 $self->{_activity} = 607 $self->{_activity} =
540 $self->{_ractivity} = 608 $self->{_ractivity} =
541 $self->{_wactivity} = AE::now; 609 $self->{_wactivity} = AE::now;
542 610
611 $self->{read_size} ||= 2048;
612 $self->{max_read_size} = $self->{read_size}
613 if $self->{read_size} > ($self->{max_read_size} || MAX_READ_SIZE);
614
543 $self->timeout (delete $self->{timeout} ) if $self->{timeout}; 615 $self->timeout (delete $self->{timeout} ) if $self->{timeout};
544 $self->rtimeout (delete $self->{rtimeout} ) if $self->{rtimeout}; 616 $self->rtimeout (delete $self->{rtimeout} ) if $self->{rtimeout};
545 $self->wtimeout (delete $self->{wtimeout} ) if $self->{wtimeout}; 617 $self->wtimeout (delete $self->{wtimeout} ) if $self->{wtimeout};
546 618
547 $self->no_delay (delete $self->{no_delay} ) if exists $self->{no_delay} && $self->{no_delay}; 619 $self->no_delay (delete $self->{no_delay} ) if exists $self->{no_delay} && $self->{no_delay};
… …
550 $self->oobinline (exists $self->{oobinline} ? delete $self->{oobinline} : 1); 622 $self->oobinline (exists $self->{oobinline} ? delete $self->{oobinline} : 1);
551 623
552 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx}) 624 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx})
553 if $self->{tls}; 625 if $self->{tls};
554 626
555 $self->on_drain (delete $self->{on_drain}) if $self->{on_drain}; 627 $self->on_drain (delete $self->{on_drain} ) if $self->{on_drain};
556 628
557 $self->start_read 629 $self->start_read
558 if $self->{on_read} || @{ $self->{_queue} }; 630 if $self->{on_read} || @{ $self->{_queue} };
559 631
560 $self->_drain_wbuf; 632 $self->_drain_wbuf;
… …
636=cut 708=cut
637 709
638sub no_delay { 710sub no_delay {
639 $_[0]{no_delay} = $_[1]; 711 $_[0]{no_delay} = $_[1];
640 712
641 eval {
642 local $SIG{__DIE__};
643 setsockopt $_[0]{fh}, Socket::IPPROTO_TCP (), Socket::TCP_NODELAY (), int $_[1] 713 setsockopt $_[0]{fh}, Socket::IPPROTO_TCP (), Socket::TCP_NODELAY (), int $_[1]
644 if $_[0]{fh}; 714 if $_[0]{fh};
645 };
646} 715}
647 716
648=item $handle->keepalive ($boolean) 717=item $handle->keepalive ($boolean)
649 718
650Enables or disables the C<keepalive> setting (see constructor argument of 719Enables or disables the C<keepalive> setting (see constructor argument of
… …
718 787
719=item $handle->rbuf_max ($max_octets) 788=item $handle->rbuf_max ($max_octets)
720 789
721Configures the C<rbuf_max> setting (C<undef> disables it). 790Configures the C<rbuf_max> setting (C<undef> disables it).
722 791
792=item $handle->wbuf_max ($max_octets)
793
794Configures the C<wbuf_max> setting (C<undef> disables it).
795
723=cut 796=cut
724 797
725sub rbuf_max { 798sub rbuf_max {
726 $_[0]{rbuf_max} = $_[1]; 799 $_[0]{rbuf_max} = $_[1];
727} 800}
728 801
802sub wbuf_max {
803 $_[0]{wbuf_max} = $_[1];
804}
805
729############################################################################# 806#############################################################################
730 807
731=item $handle->timeout ($seconds) 808=item $handle->timeout ($seconds)
732 809
733=item $handle->rtimeout ($seconds) 810=item $handle->rtimeout ($seconds)
734 811
735=item $handle->wtimeout ($seconds) 812=item $handle->wtimeout ($seconds)
736 813
737Configures (or disables) the inactivity timeout. 814Configures (or disables) the inactivity timeout.
815
816The timeout will be checked instantly, so this method might destroy the
817handle before it returns.
738 818
739=item $handle->timeout_reset 819=item $handle->timeout_reset
740 820
741=item $handle->rtimeout_reset 821=item $handle->rtimeout_reset
742 822
… …
759 $_[0]{$on_timeout} = $_[1]; 839 $_[0]{$on_timeout} = $_[1];
760 }; 840 };
761 841
762 *$timeout = sub { 842 *$timeout = sub {
763 my ($self, $new_value) = @_; 843 my ($self, $new_value) = @_;
844
845 $new_value >= 0
846 or Carp::croak "AnyEvent::Handle->$timeout called with negative timeout ($new_value), caught";
764 847
765 $self->{$timeout} = $new_value; 848 $self->{$timeout} = $new_value;
766 delete $self->{$tw}; &$cb; 849 delete $self->{$tw}; &$cb;
767 }; 850 };
768 851
… …
823 906
824The write queue is very simple: you can add data to its end, and 907The write queue is very simple: you can add data to its end, and
825AnyEvent::Handle will automatically try to get rid of it for you. 908AnyEvent::Handle will automatically try to get rid of it for you.
826 909
827When data could be written and the write buffer is shorter then the low 910When data could be written and the write buffer is shorter then the low
828water mark, the C<on_drain> callback will be invoked. 911water mark, the C<on_drain> callback will be invoked once.
829 912
830=over 4 913=over 4
831 914
832=item $handle->on_drain ($cb) 915=item $handle->on_drain ($cb)
833 916
… …
848 if $cb && $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf}); 931 if $cb && $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf});
849} 932}
850 933
851=item $handle->push_write ($data) 934=item $handle->push_write ($data)
852 935
853Queues the given scalar to be written. You can push as much data as you 936Queues the given scalar to be written. You can push as much data as
854want (only limited by the available memory), as C<AnyEvent::Handle> 937you want (only limited by the available memory and C<wbuf_max>), as
855buffers it independently of the kernel. 938C<AnyEvent::Handle> buffers it independently of the kernel.
856 939
857This method may invoke callbacks (and therefore the handle might be 940This method may invoke callbacks (and therefore the handle might be
858destroyed after it returns). 941destroyed after it returns).
859 942
860=cut 943=cut
… …
888 $cb->() unless $self->{autocork}; 971 $cb->() unless $self->{autocork};
889 972
890 # if still data left in wbuf, we need to poll 973 # if still data left in wbuf, we need to poll
891 $self->{_ww} = AE::io $self->{fh}, 1, $cb 974 $self->{_ww} = AE::io $self->{fh}, 1, $cb
892 if length $self->{wbuf}; 975 if length $self->{wbuf};
976
977 if (
978 defined $self->{wbuf_max}
979 && $self->{wbuf_max} < length $self->{wbuf}
980 ) {
981 $self->_error (Errno::ENOSPC, 1), return;
982 }
893 }; 983 };
894} 984}
895 985
896our %WH; 986our %WH;
897 987
… …
927 1017
928Instead of formatting your data yourself, you can also let this module 1018Instead of formatting your data yourself, you can also let this module
929do the job by specifying a type and type-specific arguments. You 1019do the job by specifying a type and type-specific arguments. You
930can also specify the (fully qualified) name of a package, in which 1020can also specify the (fully qualified) name of a package, in which
931case AnyEvent tries to load the package and then expects to find the 1021case AnyEvent tries to load the package and then expects to find the
932C<anyevent_read_type> function inside (see "custom write types", below). 1022C<anyevent_write_type> function inside (see "custom write types", below).
933 1023
934Predefined types are (if you have ideas for additional types, feel free to 1024Predefined types are (if you have ideas for additional types, feel free to
935drop by and tell us): 1025drop by and tell us):
936 1026
937=over 4 1027=over 4
… …
976 1066
977The generated JSON text is guaranteed not to contain any newlines: While 1067The generated JSON text is guaranteed not to contain any newlines: While
978this module doesn't need delimiters after or between JSON texts to be 1068this module doesn't need delimiters after or between JSON texts to be
979able to read them, many other languages depend on that. 1069able to read them, many other languages depend on that.
980 1070
981A simple RPC protocol that interoperates easily with others is to send 1071A simple RPC protocol that interoperates easily with other languages is
982JSON arrays (or objects, although arrays are usually the better choice as 1072to send JSON arrays (or objects, although arrays are usually the better
983they mimic how function argument passing works) and a newline after each 1073choice as they mimic how function argument passing works) and a newline
984JSON text: 1074after each JSON text:
985 1075
986 $handle->push_write (json => ["method", "arg1", "arg2"]); # whatever 1076 $handle->push_write (json => ["method", "arg1", "arg2"]); # whatever
987 $handle->push_write ("\012"); 1077 $handle->push_write ("\012");
988 1078
989An AnyEvent::Handle receiver would simply use the C<json> read type and 1079An AnyEvent::Handle receiver would simply use the C<json> read type and
… …
992 $handle->push_read (json => sub { my $array = $_[1]; ... }); 1082 $handle->push_read (json => sub { my $array = $_[1]; ... });
993 1083
994Other languages could read single lines terminated by a newline and pass 1084Other languages could read single lines terminated by a newline and pass
995this line into their JSON decoder of choice. 1085this line into their JSON decoder of choice.
996 1086
1087=item cbor => $perl_scalar
1088
1089Encodes the given scalar into a CBOR value. Unless you provide your own
1090L<CBOR::XS> object, this means it will be encoded to a CBOR string not
1091using any extensions, if possible.
1092
1093CBOR values are self-delimiting, so you can write CBOR at one end of
1094a handle and read them at the other end without using any additional
1095framing.
1096
1097A simple nd very very fast RPC protocol that interoperates with
1098other languages is to send CBOR and receive CBOR values (arrays are
1099recommended):
1100
1101 $handle->push_write (cbor => ["method", "arg1", "arg2"]); # whatever
1102
1103An AnyEvent::Handle receiver would simply use the C<cbor> read type:
1104
1105 $handle->push_read (cbor => sub { my $array = $_[1]; ... });
1106
997=cut 1107=cut
998 1108
999sub json_coder() { 1109sub json_coder() {
1000 eval { require JSON::XS; JSON::XS->new->utf8 } 1110 eval { require JSON::XS; JSON::XS->new->utf8 }
1001 || do { require JSON; JSON->new->utf8 } 1111 || do { require JSON; JSON->new->utf8 }
1002} 1112}
1003 1113
1004register_write_type json => sub { 1114register_write_type json => sub {
1005 my ($self, $ref) = @_; 1115 my ($self, $ref) = @_;
1006 1116
1007 my $json = $self->{json} ||= json_coder; 1117 ($self->{json} ||= json_coder)
1008
1009 $json->encode ($ref) 1118 ->encode ($ref)
1119};
1120
1121sub cbor_coder() {
1122 require CBOR::XS;
1123 CBOR::XS->new
1124}
1125
1126register_write_type cbor => sub {
1127 my ($self, $scalar) = @_;
1128
1129 ($self->{cbor} ||= cbor_coder)
1130 ->encode ($scalar)
1010}; 1131};
1011 1132
1012=item storable => $reference 1133=item storable => $reference
1013 1134
1014Freezes the given reference using L<Storable> and writes it to the 1135Freezes the given reference using L<Storable> and writes it to the
… …
1017=cut 1138=cut
1018 1139
1019register_write_type storable => sub { 1140register_write_type storable => sub {
1020 my ($self, $ref) = @_; 1141 my ($self, $ref) = @_;
1021 1142
1022 require Storable; 1143 require Storable unless $Storable::VERSION;
1023 1144
1024 pack "w/a*", Storable::nfreeze ($ref) 1145 pack "w/a*", Storable::nfreeze ($ref)
1025}; 1146};
1026 1147
1027=back 1148=back
… …
1032before it was actually written. One way to do that is to replace your 1153before it was actually written. One way to do that is to replace your
1033C<on_drain> handler by a callback that shuts down the socket (and set 1154C<on_drain> handler by a callback that shuts down the socket (and set
1034C<low_water_mark> to C<0>). This method is a shorthand for just that, and 1155C<low_water_mark> to C<0>). This method is a shorthand for just that, and
1035replaces the C<on_drain> callback with: 1156replaces the C<on_drain> callback with:
1036 1157
1037 sub { shutdown $_[0]{fh}, 1 } # for push_shutdown 1158 sub { shutdown $_[0]{fh}, 1 }
1038 1159
1039This simply shuts down the write side and signals an EOF condition to the 1160This simply shuts down the write side and signals an EOF condition to the
1040the peer. 1161the peer.
1041 1162
1042You can rely on the normal read queue and C<on_eof> handling 1163You can rely on the normal read queue and C<on_eof> handling
… …
1064 1185
1065Whenever the given C<type> is used, C<push_write> will the function with 1186Whenever the given C<type> is used, C<push_write> will the function with
1066the handle object and the remaining arguments. 1187the handle object and the remaining arguments.
1067 1188
1068The function is supposed to return a single octet string that will be 1189The function is supposed to return a single octet string that will be
1069appended to the write buffer, so you cna mentally treat this function as a 1190appended to the write buffer, so you can mentally treat this function as a
1070"arguments to on-the-wire-format" converter. 1191"arguments to on-the-wire-format" converter.
1071 1192
1072Example: implement a custom write type C<join> that joins the remaining 1193Example: implement a custom write type C<join> that joins the remaining
1073arguments using the first one. 1194arguments using the first one.
1074 1195
… …
1101ways, the "simple" way, using only C<on_read> and the "complex" way, using 1222ways, the "simple" way, using only C<on_read> and the "complex" way, using
1102a queue. 1223a queue.
1103 1224
1104In the simple case, you just install an C<on_read> callback and whenever 1225In the simple case, you just install an C<on_read> callback and whenever
1105new data arrives, it will be called. You can then remove some data (if 1226new data arrives, it will be called. You can then remove some data (if
1106enough is there) from the read buffer (C<< $handle->rbuf >>). Or you cna 1227enough is there) from the read buffer (C<< $handle->rbuf >>). Or you can
1107leave the data there if you want to accumulate more (e.g. when only a 1228leave the data there if you want to accumulate more (e.g. when only a
1108partial message has been received so far). 1229partial message has been received so far), or change the read queue with
1230e.g. C<push_read>.
1109 1231
1110In the more complex case, you want to queue multiple callbacks. In this 1232In the more complex case, you want to queue multiple callbacks. In this
1111case, AnyEvent::Handle will call the first queued callback each time new 1233case, AnyEvent::Handle will call the first queued callback each time new
1112data arrives (also the first time it is queued) and removes it when it has 1234data arrives (also the first time it is queued) and remove it when it has
1113done its job (see C<push_read>, below). 1235done its job (see C<push_read>, below).
1114 1236
1115This way you can, for example, push three line-reads, followed by reading 1237This way you can, for example, push three line-reads, followed by reading
1116a chunk of data, and AnyEvent::Handle will execute them in order. 1238a chunk of data, and AnyEvent::Handle will execute them in order.
1117 1239
… …
1262 $self->_drain_rbuf if $cb; 1384 $self->_drain_rbuf if $cb;
1263} 1385}
1264 1386
1265=item $handle->rbuf 1387=item $handle->rbuf
1266 1388
1267Returns the read buffer (as a modifiable lvalue). 1389Returns the read buffer (as a modifiable lvalue). You can also access the
1390read buffer directly as the C<< ->{rbuf} >> member, if you want (this is
1391much faster, and no less clean).
1268 1392
1269You can access the read buffer directly as the C<< ->{rbuf} >> 1393The only operation allowed on the read buffer (apart from looking at it)
1270member, if you want. However, the only operation allowed on the 1394is removing data from its beginning. Otherwise modifying or appending to
1271read buffer (apart from looking at it) is removing data from its 1395it is not allowed and will lead to hard-to-track-down bugs.
1272beginning. Otherwise modifying or appending to it is not allowed and will
1273lead to hard-to-track-down bugs.
1274 1396
1275NOTE: The read buffer should only be used or modified if the C<on_read>, 1397NOTE: The read buffer should only be used or modified in the C<on_read>
1276C<push_read> or C<unshift_read> methods are used. The other read methods 1398callback or when C<push_read> or C<unshift_read> are used with a single
1277automatically manage the read buffer. 1399callback (i.e. untyped). Typed C<push_read> and C<unshift_read> methods
1400will manage the read buffer on their own.
1278 1401
1279=cut 1402=cut
1280 1403
1281sub rbuf : lvalue { 1404sub rbuf : lvalue {
1282 $_[0]{rbuf} 1405 $_[0]{rbuf}
… …
1333 my $cb = pop; 1456 my $cb = pop;
1334 1457
1335 if (@_) { 1458 if (@_) {
1336 my $type = shift; 1459 my $type = shift;
1337 1460
1461 $cb = ($RH{$type} ||= _load_func "$type\::anyevent_read_type"
1338 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::unshift_read") 1462 or Carp::croak "unsupported/unloadable type '$type' passed to AnyEvent::Handle::unshift_read")
1339 ->($self, $cb, @_); 1463 ->($self, $cb, @_);
1340 } 1464 }
1341 1465
1342 unshift @{ $self->{_queue} }, $cb; 1466 unshift @{ $self->{_queue} }, $cb;
1343 $self->_drain_rbuf; 1467 $self->_drain_rbuf;
… …
1365data. 1489data.
1366 1490
1367Example: read 2 bytes. 1491Example: read 2 bytes.
1368 1492
1369 $handle->push_read (chunk => 2, sub { 1493 $handle->push_read (chunk => 2, sub {
1370 warn "yay ", unpack "H*", $_[1]; 1494 say "yay " . unpack "H*", $_[1];
1371 }); 1495 });
1372 1496
1373=cut 1497=cut
1374 1498
1375register_read_type chunk => sub { 1499register_read_type chunk => sub {
… …
1405 1529
1406register_read_type line => sub { 1530register_read_type line => sub {
1407 my ($self, $cb, $eol) = @_; 1531 my ($self, $cb, $eol) = @_;
1408 1532
1409 if (@_ < 3) { 1533 if (@_ < 3) {
1410 # this is more than twice as fast as the generic code below 1534 # this is faster then the generic code below
1411 sub { 1535 sub {
1412 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return; 1536 (my $pos = index $_[0]{rbuf}, "\012") >= 0
1537 or return;
1413 1538
1539 (my $str = substr $_[0]{rbuf}, 0, $pos + 1, "") =~ s/(\015?\012)\Z// or die;
1414 $cb->($_[0], $1, $2); 1540 $cb->($_[0], $str, "$1");
1415 1 1541 1
1416 } 1542 }
1417 } else { 1543 } else {
1418 $eol = quotemeta $eol unless ref $eol; 1544 $eol = quotemeta $eol unless ref $eol;
1419 $eol = qr|^(.*?)($eol)|s; 1545 $eol = qr|^(.*?)($eol)|s;
1420 1546
1421 sub { 1547 sub {
1422 $_[0]{rbuf} =~ s/$eol// or return; 1548 $_[0]{rbuf} =~ s/$eol// or return;
1423 1549
1424 $cb->($_[0], $1, $2); 1550 $cb->($_[0], "$1", "$2");
1425 1 1551 1
1426 } 1552 }
1427 } 1553 }
1428}; 1554};
1429 1555
… …
1451the receive buffer when neither C<$accept> nor C<$reject> match, 1577the receive buffer when neither C<$accept> nor C<$reject> match,
1452and everything preceding and including the match will be accepted 1578and everything preceding and including the match will be accepted
1453unconditionally. This is useful to skip large amounts of data that you 1579unconditionally. This is useful to skip large amounts of data that you
1454know cannot be matched, so that the C<$accept> or C<$reject> regex do not 1580know cannot be matched, so that the C<$accept> or C<$reject> regex do not
1455have to start matching from the beginning. This is purely an optimisation 1581have to start matching from the beginning. This is purely an optimisation
1456and is usually worth only when you expect more than a few kilobytes. 1582and is usually worth it only when you expect more than a few kilobytes.
1457 1583
1458Example: expect a http header, which ends at C<\015\012\015\012>. Since we 1584Example: expect a http header, which ends at C<\015\012\015\012>. Since we
1459expect the header to be very large (it isn't in practise, but...), we use 1585expect the header to be very large (it isn't in practice, but...), we use
1460a skip regex to skip initial portions. The skip regex is tricky in that 1586a skip regex to skip initial portions. The skip regex is tricky in that
1461it only accepts something not ending in either \015 or \012, as these are 1587it only accepts something not ending in either \015 or \012, as these are
1462required for the accept regex. 1588required for the accept regex.
1463 1589
1464 $handle->push_read (regex => 1590 $handle->push_read (regex =>
… …
1477 1603
1478 sub { 1604 sub {
1479 # accept 1605 # accept
1480 if ($$rbuf =~ $accept) { 1606 if ($$rbuf =~ $accept) {
1481 $data .= substr $$rbuf, 0, $+[0], ""; 1607 $data .= substr $$rbuf, 0, $+[0], "";
1482 $cb->($self, $data); 1608 $cb->($_[0], $data);
1483 return 1; 1609 return 1;
1484 } 1610 }
1485 1611
1486 # reject 1612 # reject
1487 if ($reject && $$rbuf =~ $reject) { 1613 if ($reject && $$rbuf =~ $reject) {
1488 $self->_error (Errno::EBADMSG); 1614 $_[0]->_error (Errno::EBADMSG);
1489 } 1615 }
1490 1616
1491 # skip 1617 # skip
1492 if ($skip && $$rbuf =~ $skip) { 1618 if ($skip && $$rbuf =~ $skip) {
1493 $data .= substr $$rbuf, 0, $+[0], ""; 1619 $data .= substr $$rbuf, 0, $+[0], "";
… …
1509 my ($self, $cb) = @_; 1635 my ($self, $cb) = @_;
1510 1636
1511 sub { 1637 sub {
1512 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) { 1638 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) {
1513 if ($_[0]{rbuf} =~ /[^0-9]/) { 1639 if ($_[0]{rbuf} =~ /[^0-9]/) {
1514 $self->_error (Errno::EBADMSG); 1640 $_[0]->_error (Errno::EBADMSG);
1515 } 1641 }
1516 return; 1642 return;
1517 } 1643 }
1518 1644
1519 my $len = $1; 1645 my $len = $1;
1520 1646
1521 $self->unshift_read (chunk => $len, sub { 1647 $_[0]->unshift_read (chunk => $len, sub {
1522 my $string = $_[1]; 1648 my $string = $_[1];
1523 $_[0]->unshift_read (chunk => 1, sub { 1649 $_[0]->unshift_read (chunk => 1, sub {
1524 if ($_[1] eq ",") { 1650 if ($_[1] eq ",") {
1525 $cb->($_[0], $string); 1651 $cb->($_[0], $string);
1526 } else { 1652 } else {
1527 $self->_error (Errno::EBADMSG); 1653 $_[0]->_error (Errno::EBADMSG);
1528 } 1654 }
1529 }); 1655 });
1530 }); 1656 });
1531 1657
1532 1 1658 1
… …
1602 my ($self, $cb) = @_; 1728 my ($self, $cb) = @_;
1603 1729
1604 my $json = $self->{json} ||= json_coder; 1730 my $json = $self->{json} ||= json_coder;
1605 1731
1606 my $data; 1732 my $data;
1607 my $rbuf = \$self->{rbuf};
1608 1733
1609 sub { 1734 sub {
1610 my $ref = eval { $json->incr_parse ($self->{rbuf}) }; 1735 my $ref = eval { $json->incr_parse ($_[0]{rbuf}) };
1611 1736
1612 if ($ref) { 1737 if ($ref) {
1613 $self->{rbuf} = $json->incr_text; 1738 $_[0]{rbuf} = $json->incr_text;
1614 $json->incr_text = ""; 1739 $json->incr_text = "";
1615 $cb->($self, $ref); 1740 $cb->($_[0], $ref);
1616 1741
1617 1 1742 1
1618 } elsif ($@) { 1743 } elsif ($@) {
1619 # error case 1744 # error case
1620 $json->incr_skip; 1745 $json->incr_skip;
1621 1746
1622 $self->{rbuf} = $json->incr_text; 1747 $_[0]{rbuf} = $json->incr_text;
1623 $json->incr_text = ""; 1748 $json->incr_text = "";
1624 1749
1625 $self->_error (Errno::EBADMSG); 1750 $_[0]->_error (Errno::EBADMSG);
1626 1751
1627 () 1752 ()
1628 } else { 1753 } else {
1629 $self->{rbuf} = ""; 1754 $_[0]{rbuf} = "";
1630 1755
1756 ()
1757 }
1758 }
1759};
1760
1761=item cbor => $cb->($handle, $scalar)
1762
1763Reads a CBOR value, decodes it and passes it to the callback. When a parse
1764error occurs, an C<EBADMSG> error will be raised.
1765
1766If a L<CBOR::XS> object was passed to the constructor, then that will be
1767used for the final decode, otherwise it will create a CBOR coder without
1768enabling any options.
1769
1770You have to provide a dependency to L<CBOR::XS> on your own: this module
1771will load the L<CBOR::XS> module, but AnyEvent does not depend on it
1772itself.
1773
1774Since CBOR values are fully self-delimiting, the C<cbor> read and write
1775types are an ideal simple RPC protocol: just exchange CBOR datagrams. See
1776the C<cbor> write type description, above, for an actual example.
1777
1778=cut
1779
1780register_read_type cbor => sub {
1781 my ($self, $cb) = @_;
1782
1783 my $cbor = $self->{cbor} ||= cbor_coder;
1784
1785 my $data;
1786
1787 sub {
1788 my (@value) = eval { $cbor->incr_parse ($_[0]{rbuf}) };
1789
1790 if (@value) {
1791 $cb->($_[0], @value);
1792
1793 1
1794 } elsif ($@) {
1795 # error case
1796 $cbor->incr_reset;
1797
1798 $_[0]->_error (Errno::EBADMSG);
1799
1800 ()
1801 } else {
1631 () 1802 ()
1632 } 1803 }
1633 } 1804 }
1634}; 1805};
1635 1806
… …
1644=cut 1815=cut
1645 1816
1646register_read_type storable => sub { 1817register_read_type storable => sub {
1647 my ($self, $cb) = @_; 1818 my ($self, $cb) = @_;
1648 1819
1649 require Storable; 1820 require Storable unless $Storable::VERSION;
1650 1821
1651 sub { 1822 sub {
1652 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method 1823 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method
1653 defined (my $len = eval { unpack "w", $_[0]{rbuf} }) 1824 defined (my $len = eval { unpack "w", $_[0]{rbuf} })
1654 or return; 1825 or return;
… …
1657 1828
1658 # bypass unshift if we already have the remaining chunk 1829 # bypass unshift if we already have the remaining chunk
1659 if ($format + $len <= length $_[0]{rbuf}) { 1830 if ($format + $len <= length $_[0]{rbuf}) {
1660 my $data = substr $_[0]{rbuf}, $format, $len; 1831 my $data = substr $_[0]{rbuf}, $format, $len;
1661 substr $_[0]{rbuf}, 0, $format + $len, ""; 1832 substr $_[0]{rbuf}, 0, $format + $len, "";
1833
1662 $cb->($_[0], Storable::thaw ($data)); 1834 eval { $cb->($_[0], Storable::thaw ($data)); 1 }
1835 or return $_[0]->_error (Errno::EBADMSG);
1663 } else { 1836 } else {
1664 # remove prefix 1837 # remove prefix
1665 substr $_[0]{rbuf}, 0, $format, ""; 1838 substr $_[0]{rbuf}, 0, $format, "";
1666 1839
1667 # read remaining chunk 1840 # read remaining chunk
1668 $_[0]->unshift_read (chunk => $len, sub { 1841 $_[0]->unshift_read (chunk => $len, sub {
1669 if (my $ref = eval { Storable::thaw ($_[1]) }) { 1842 eval { $cb->($_[0], Storable::thaw ($_[1])); 1 }
1670 $cb->($_[0], $ref);
1671 } else {
1672 $self->_error (Errno::EBADMSG); 1843 or $_[0]->_error (Errno::EBADMSG);
1673 }
1674 }); 1844 });
1675 } 1845 }
1676 1846
1677 1 1847 1
1678 } 1848 }
1849};
1850
1851=item tls_detect => $cb->($handle, $detect, $major, $minor)
1852
1853Checks the input stream for a valid SSL or TLS handshake TLSPaintext
1854record without consuming anything. Only SSL version 3 or higher
1855is handled, up to the fictituous protocol 4.x (but both SSL3+ and
1856SSL2-compatible framing is supported).
1857
1858If it detects that the input data is likely TLS, it calls the callback
1859with a true value for C<$detect> and the (on-wire) TLS version as second
1860and third argument (C<$major> is C<3>, and C<$minor> is 0..3 for SSL
18613.0, TLS 1.0, 1.1 and 1.2, respectively). If it detects the input to
1862be definitely not TLS, it calls the callback with a false value for
1863C<$detect>.
1864
1865The callback could use this information to decide whether or not to start
1866TLS negotiation.
1867
1868In all cases the data read so far is passed to the following read
1869handlers.
1870
1871Usually you want to use the C<tls_autostart> read type instead.
1872
1873If you want to design a protocol that works in the presence of TLS
1874dtection, make sure that any non-TLS data doesn't start with the octet 22
1875(ASCII SYN, 16 hex) or 128-255 (i.e. highest bit set). The checks this
1876read type does are a bit more strict, but might losen in the future to
1877accomodate protocol changes.
1878
1879This read type does not rely on L<AnyEvent::TLS> (and thus, not on
1880L<Net::SSLeay>).
1881
1882=item tls_autostart => $tls[, $tls_ctx]
1883
1884Tries to detect a valid SSL or TLS handshake. If one is detected, it tries
1885to start tls by calling C<starttls> with the given arguments.
1886
1887In practise, C<$tls> must be C<accept>, or a Net::SSLeay context that has
1888been configured to accept, as servers do not normally send a handshake on
1889their own and ths cannot be detected in this way.
1890
1891See C<tls_detect> above for more details.
1892
1893Example: give the client a chance to start TLS before accepting a text
1894line.
1895
1896 $hdl->push_read (tls_detect => "accept");
1897 $hdl->push_read (line => sub {
1898 print "received ", ($_[0]{tls} ? "encrypted" : "cleartext"), " <$_[1]>\n";
1899 });
1900
1901=cut
1902
1903register_read_type tls_detect => sub {
1904 my ($self, $cb) = @_;
1905
1906 sub {
1907 # this regex matches a full or partial tls record
1908 if (
1909 # ssl3+: type(22=handshake) major(=3) minor(any) length_hi
1910 $self->{rbuf} =~ /^(?:\z| \x16 (\z| [\x03\x04] (?:\z| . (?:\z| [\x00-\x40] ))))/xs
1911 # ssl2 comapatible: len_hi len_lo type(1) major minor dummy(forlength)
1912 or $self->{rbuf} =~ /^(?:\z| [\x80-\xff] (?:\z| . (?:\z| \x01 (\z| [\x03\x04] (?:\z| . (?:\z| . ))))))/xs
1913 ) {
1914 return if 3 != length $1; # partial match, can't decide yet
1915
1916 # full match, valid TLS record
1917 my ($major, $minor) = unpack "CC", $1;
1918 $cb->($self, "accept", $major + $minor * 0.1);
1919 } else {
1920 # mismatch == guaranteed not TLS
1921 $cb->($self, undef);
1922 }
1923
1924 1
1925 }
1926};
1927
1928register_read_type tls_autostart => sub {
1929 my ($self, @tls) = @_;
1930
1931 $RH{tls_detect}($self, sub {
1932 return unless $_[1];
1933 $_[0]->starttls (@tls);
1934 })
1679}; 1935};
1680 1936
1681=back 1937=back
1682 1938
1683=item custom read types - Package::anyevent_read_type $handle, $cb, @args 1939=item custom read types - Package::anyevent_read_type $handle, $cb, @args
… …
1715Note that AnyEvent::Handle will automatically C<start_read> for you when 1971Note that AnyEvent::Handle will automatically C<start_read> for you when
1716you change the C<on_read> callback or push/unshift a read callback, and it 1972you change the C<on_read> callback or push/unshift a read callback, and it
1717will automatically C<stop_read> for you when neither C<on_read> is set nor 1973will automatically C<stop_read> for you when neither C<on_read> is set nor
1718there are any read requests in the queue. 1974there are any read requests in the queue.
1719 1975
1720These methods will have no effect when in TLS mode (as TLS doesn't support 1976In older versions of this module (<= 5.3), these methods had no effect,
1721half-duplex connections). 1977as TLS does not support half-duplex connections. In current versions they
1978work as expected, as this behaviour is required to avoid certain resource
1979attacks, where the program would be forced to read (and buffer) arbitrary
1980amounts of data before being able to send some data. The drawback is that
1981some readings of the the SSL/TLS specifications basically require this
1982attack to be working, as SSL/TLS implementations might stall sending data
1983during a rehandshake.
1984
1985As a guideline, during the initial handshake, you should not stop reading,
1986and as a client, it might cause problems, depending on your application.
1722 1987
1723=cut 1988=cut
1724 1989
1725sub stop_read { 1990sub stop_read {
1726 my ($self) = @_; 1991 my ($self) = @_;
1727 1992
1728 delete $self->{_rw} unless $self->{tls}; 1993 delete $self->{_rw};
1729} 1994}
1730 1995
1731sub start_read { 1996sub start_read {
1732 my ($self) = @_; 1997 my ($self) = @_;
1733 1998
1734 unless ($self->{_rw} || $self->{_eof} || !$self->{fh}) { 1999 unless ($self->{_rw} || $self->{_eof} || !$self->{fh}) {
1735 Scalar::Util::weaken $self; 2000 Scalar::Util::weaken $self;
1736 2001
1737 $self->{_rw} = AE::io $self->{fh}, 0, sub { 2002 $self->{_rw} = AE::io $self->{fh}, 0, sub {
1738 my $rbuf = \($self->{tls} ? my $buf : $self->{rbuf}); 2003 my $rbuf = \($self->{tls} ? my $buf : $self->{rbuf});
1739 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf; 2004 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size}, length $$rbuf;
1740 2005
1741 if ($len > 0) { 2006 if ($len > 0) {
1742 $self->{_activity} = $self->{_ractivity} = AE::now; 2007 $self->{_activity} = $self->{_ractivity} = AE::now;
1743 2008
1744 if ($self->{tls}) { 2009 if ($self->{tls}) {
… …
1747 &_dotls ($self); 2012 &_dotls ($self);
1748 } else { 2013 } else {
1749 $self->_drain_rbuf; 2014 $self->_drain_rbuf;
1750 } 2015 }
1751 2016
2017 if ($len == $self->{read_size}) {
2018 $self->{read_size} *= 2;
2019 $self->{read_size} = $self->{max_read_size} || MAX_READ_SIZE
2020 if $self->{read_size} > ($self->{max_read_size} || MAX_READ_SIZE);
2021 }
2022
1752 } elsif (defined $len) { 2023 } elsif (defined $len) {
1753 delete $self->{_rw}; 2024 delete $self->{_rw};
1754 $self->{_eof} = 1; 2025 $self->{_eof} = 1;
1755 $self->_drain_rbuf; 2026 $self->_drain_rbuf;
1756 2027
… …
1768 my ($self, $err) = @_; 2039 my ($self, $err) = @_;
1769 2040
1770 return $self->_error ($!, 1) 2041 return $self->_error ($!, 1)
1771 if $err == Net::SSLeay::ERROR_SYSCALL (); 2042 if $err == Net::SSLeay::ERROR_SYSCALL ();
1772 2043
1773 my $err =Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ()); 2044 my $err = Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ());
1774 2045
1775 # reduce error string to look less scary 2046 # reduce error string to look less scary
1776 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /; 2047 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /;
1777 2048
1778 if ($self->{_on_starttls}) { 2049 if ($self->{_on_starttls}) {
… …
1844 2115
1845=item $handle->starttls ($tls[, $tls_ctx]) 2116=item $handle->starttls ($tls[, $tls_ctx])
1846 2117
1847Instead of starting TLS negotiation immediately when the AnyEvent::Handle 2118Instead of starting TLS negotiation immediately when the AnyEvent::Handle
1848object is created, you can also do that at a later time by calling 2119object is created, you can also do that at a later time by calling
1849C<starttls>. 2120C<starttls>. See the C<tls> constructor argument for general info.
1850 2121
1851Starting TLS is currently an asynchronous operation - when you push some 2122Starting TLS is currently an asynchronous operation - when you push some
1852write data and then call C<< ->starttls >> then TLS negotiation will start 2123write data and then call C<< ->starttls >> then TLS negotiation will start
1853immediately, after which the queued write data is then sent. 2124immediately, after which the queued write data is then sent. This might
2125change in future versions, so best make sure you have no outstanding write
2126data when calling this method.
1854 2127
1855The first argument is the same as the C<tls> constructor argument (either 2128The first argument is the same as the C<tls> constructor argument (either
1856C<"connect">, C<"accept"> or an existing Net::SSLeay object). 2129C<"connect">, C<"accept"> or an existing Net::SSLeay object).
1857 2130
1858The second argument is the optional C<AnyEvent::TLS> object that is used 2131The second argument is the optional C<AnyEvent::TLS> object that is used
… …
1864context in C<< $handle->{tls_ctx} >> after this call and can be used or 2137context in C<< $handle->{tls_ctx} >> after this call and can be used or
1865changed to your liking. Note that the handshake might have already started 2138changed to your liking. Note that the handshake might have already started
1866when this function returns. 2139when this function returns.
1867 2140
1868Due to bugs in OpenSSL, it might or might not be possible to do multiple 2141Due to bugs in OpenSSL, it might or might not be possible to do multiple
1869handshakes on the same stream. Best do not attempt to use the stream after 2142handshakes on the same stream. It is best to not attempt to use the
1870stopping TLS. 2143stream after stopping TLS.
1871 2144
1872This method may invoke callbacks (and therefore the handle might be 2145This method may invoke callbacks (and therefore the handle might be
1873destroyed after it returns). 2146destroyed after it returns).
1874 2147
1875=cut 2148=cut
… …
1880 my ($self, $tls, $ctx) = @_; 2153 my ($self, $tls, $ctx) = @_;
1881 2154
1882 Carp::croak "It is an error to call starttls on an AnyEvent::Handle object while TLS is already active, caught" 2155 Carp::croak "It is an error to call starttls on an AnyEvent::Handle object while TLS is already active, caught"
1883 if $self->{tls}; 2156 if $self->{tls};
1884 2157
2158 unless (defined $AnyEvent::TLS::VERSION) {
2159 eval {
2160 require Net::SSLeay;
2161 require AnyEvent::TLS;
2162 1
2163 } or return $self->_error (Errno::EPROTO, 1, "TLS support not available on this system");
2164 }
2165
1885 $self->{tls} = $tls; 2166 $self->{tls} = $tls;
1886 $self->{tls_ctx} = $ctx if @_ > 2; 2167 $self->{tls_ctx} = $ctx if @_ > 2;
1887 2168
1888 return unless $self->{fh}; 2169 return unless $self->{fh};
1889 2170
1890 require Net::SSLeay;
1891
1892 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL (); 2171 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL ();
1893 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ (); 2172 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ ();
1894 2173
1895 $tls = delete $self->{tls}; 2174 $tls = delete $self->{tls};
1896 $ctx = $self->{tls_ctx}; 2175 $ctx = $self->{tls_ctx};
1897 2176
1898 local $Carp::CarpLevel = 1; # skip ourselves when creating a new context or session 2177 local $Carp::CarpLevel = 1; # skip ourselves when creating a new context or session
1899 2178
1900 if ("HASH" eq ref $ctx) { 2179 if ("HASH" eq ref $ctx) {
1901 require AnyEvent::TLS;
1902
1903 if ($ctx->{cache}) { 2180 if ($ctx->{cache}) {
1904 my $key = $ctx+0; 2181 my $key = $ctx+0;
1905 $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx; 2182 $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx;
1906 } else { 2183 } else {
1907 $ctx = new AnyEvent::TLS %$ctx; 2184 $ctx = new AnyEvent::TLS %$ctx;
… …
1929 Net::SSLeay::CTX_set_mode ($tls, 1|2); 2206 Net::SSLeay::CTX_set_mode ($tls, 1|2);
1930 2207
1931 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 2208 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1932 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 2209 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1933 2210
1934 Net::SSLeay::BIO_write ($self->{_rbio}, delete $self->{rbuf}); 2211 Net::SSLeay::BIO_write ($self->{_rbio}, $self->{rbuf});
2212 $self->{rbuf} = "";
1935 2213
1936 Net::SSLeay::set_bio ($tls, $self->{_rbio}, $self->{_wbio}); 2214 Net::SSLeay::set_bio ($tls, $self->{_rbio}, $self->{_wbio});
1937 2215
1938 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) } 2216 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) }
1939 if $self->{on_starttls}; 2217 if $self->{on_starttls};
… …
1977 if $self->{tls} > 0; 2255 if $self->{tls} > 0;
1978 2256
1979 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)}; 2257 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)};
1980} 2258}
1981 2259
2260=item $handle->resettls
2261
2262This rarely-used method simply resets and TLS state on the handle, usually
2263causing data loss.
2264
2265One case where it may be useful is when you want to skip over the data in
2266the stream but you are not interested in interpreting it, so data loss is
2267no concern.
2268
2269=cut
2270
2271*resettls = \&_freetls;
2272
1982sub DESTROY { 2273sub DESTROY {
1983 my ($self) = @_; 2274 my ($self) = @_;
1984 2275
1985 &_freetls; 2276 &_freetls;
1986 2277
… …
1995 push @linger, AE::io $fh, 1, sub { 2286 push @linger, AE::io $fh, 1, sub {
1996 my $len = syswrite $fh, $wbuf, length $wbuf; 2287 my $len = syswrite $fh, $wbuf, length $wbuf;
1997 2288
1998 if ($len > 0) { 2289 if ($len > 0) {
1999 substr $wbuf, 0, $len, ""; 2290 substr $wbuf, 0, $len, "";
2000 } else { 2291 } elsif (defined $len || ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK)) {
2001 @linger = (); # end 2292 @linger = (); # end
2002 } 2293 }
2003 }; 2294 };
2004 push @linger, AE::timer $linger, 0, sub { 2295 push @linger, AE::timer $linger, 0, sub {
2005 @linger = (); 2296 @linger = ();
… …
2101 2392
2102It is only safe to "forget" the reference inside EOF or error callbacks, 2393It is only safe to "forget" the reference inside EOF or error callbacks,
2103from within all other callbacks, you need to explicitly call the C<< 2394from within all other callbacks, you need to explicitly call the C<<
2104->destroy >> method. 2395->destroy >> method.
2105 2396
2397=item Why is my C<on_eof> callback never called?
2398
2399Probably because your C<on_error> callback is being called instead: When
2400you have outstanding requests in your read queue, then an EOF is
2401considered an error as you clearly expected some data.
2402
2403To avoid this, make sure you have an empty read queue whenever your handle
2404is supposed to be "idle" (i.e. connection closes are O.K.). You can set
2405an C<on_read> handler that simply pushes the first read requests in the
2406queue.
2407
2408See also the next question, which explains this in a bit more detail.
2409
2410=item How can I serve requests in a loop?
2411
2412Most protocols consist of some setup phase (authentication for example)
2413followed by a request handling phase, where the server waits for requests
2414and handles them, in a loop.
2415
2416There are two important variants: The first (traditional, better) variant
2417handles requests until the server gets some QUIT command, causing it to
2418close the connection first (highly desirable for a busy TCP server). A
2419client dropping the connection is an error, which means this variant can
2420detect an unexpected detection close.
2421
2422To handle this case, always make sure you have a non-empty read queue, by
2423pushing the "read request start" handler on it:
2424
2425 # we assume a request starts with a single line
2426 my @start_request; @start_request = (line => sub {
2427 my ($hdl, $line) = @_;
2428
2429 ... handle request
2430
2431 # push next request read, possibly from a nested callback
2432 $hdl->push_read (@start_request);
2433 });
2434
2435 # auth done, now go into request handling loop
2436 # now push the first @start_request
2437 $hdl->push_read (@start_request);
2438
2439By always having an outstanding C<push_read>, the handle always expects
2440some data and raises the C<EPIPE> error when the connction is dropped
2441unexpectedly.
2442
2443The second variant is a protocol where the client can drop the connection
2444at any time. For TCP, this means that the server machine may run out of
2445sockets easier, and in general, it means you cannot distinguish a protocl
2446failure/client crash from a normal connection close. Nevertheless, these
2447kinds of protocols are common (and sometimes even the best solution to the
2448problem).
2449
2450Having an outstanding read request at all times is possible if you ignore
2451C<EPIPE> errors, but this doesn't help with when the client drops the
2452connection during a request, which would still be an error.
2453
2454A better solution is to push the initial request read in an C<on_read>
2455callback. This avoids an error, as when the server doesn't expect data
2456(i.e. is idly waiting for the next request, an EOF will not raise an
2457error, but simply result in an C<on_eof> callback. It is also a bit slower
2458and simpler:
2459
2460 # auth done, now go into request handling loop
2461 $hdl->on_read (sub {
2462 my ($hdl) = @_;
2463
2464 # called each time we receive data but the read queue is empty
2465 # simply start read the request
2466
2467 $hdl->push_read (line => sub {
2468 my ($hdl, $line) = @_;
2469
2470 ... handle request
2471
2472 # do nothing special when the request has been handled, just
2473 # let the request queue go empty.
2474 });
2475 });
2476
2106=item I get different callback invocations in TLS mode/Why can't I pause 2477=item I get different callback invocations in TLS mode/Why can't I pause
2107reading? 2478reading?
2108 2479
2109Unlike, say, TCP, TLS connections do not consist of two independent 2480Unlike, say, TCP, TLS connections do not consist of two independent
2110communication channels, one for each direction. Or put differently. The 2481communication channels, one for each direction. Or put differently, the
2111read and write directions are not independent of each other: you cannot 2482read and write directions are not independent of each other: you cannot
2112write data unless you are also prepared to read, and vice versa. 2483write data unless you are also prepared to read, and vice versa.
2113 2484
2114This can mean than, in TLS mode, you might get C<on_error> or C<on_eof> 2485This means that, in TLS mode, you might get C<on_error> or C<on_eof>
2115callback invocations when you are not expecting any read data - the reason 2486callback invocations when you are not expecting any read data - the reason
2116is that AnyEvent::Handle always reads in TLS mode. 2487is that AnyEvent::Handle always reads in TLS mode.
2117 2488
2118During the connection, you have to make sure that you always have a 2489During the connection, you have to make sure that you always have a
2119non-empty read-queue, or an C<on_read> watcher. At the end of the 2490non-empty read-queue, or an C<on_read> watcher. At the end of the
… …
2131 $handle->on_eof (undef); 2502 $handle->on_eof (undef);
2132 $handle->on_error (sub { 2503 $handle->on_error (sub {
2133 my $data = delete $_[0]{rbuf}; 2504 my $data = delete $_[0]{rbuf};
2134 }); 2505 });
2135 2506
2507Note that this example removes the C<rbuf> member from the handle object,
2508which is not normally allowed by the API. It is expressly permitted in
2509this case only, as the handle object needs to be destroyed afterwards.
2510
2136The reason to use C<on_error> is that TCP connections, due to latencies 2511The reason to use C<on_error> is that TCP connections, due to latencies
2137and packets loss, might get closed quite violently with an error, when in 2512and packets loss, might get closed quite violently with an error, when in
2138fact, all data has been received. 2513fact all data has been received.
2139 2514
2140It is usually better to use acknowledgements when transferring data, 2515It is usually better to use acknowledgements when transferring data,
2141to make sure the other side hasn't just died and you got the data 2516to make sure the other side hasn't just died and you got the data
2142intact. This is also one reason why so many internet protocols have an 2517intact. This is also one reason why so many internet protocols have an
2143explicit QUIT command. 2518explicit QUIT command.
… …
2150C<low_water_mark> this will be called precisely when all data has been 2525C<low_water_mark> this will be called precisely when all data has been
2151written to the socket: 2526written to the socket:
2152 2527
2153 $handle->push_write (...); 2528 $handle->push_write (...);
2154 $handle->on_drain (sub { 2529 $handle->on_drain (sub {
2155 warn "all data submitted to the kernel\n"; 2530 AE::log debug => "All data submitted to the kernel.";
2156 undef $handle; 2531 undef $handle;
2157 }); 2532 });
2158 2533
2159If you just want to queue some data and then signal EOF to the other side, 2534If you just want to queue some data and then signal EOF to the other side,
2160consider using C<< ->push_shutdown >> instead. 2535consider using C<< ->push_shutdown >> instead.
2161 2536
2162=item I want to contact a TLS/SSL server, I don't care about security. 2537=item I want to contact a TLS/SSL server, I don't care about security.
2163 2538
2164If your TLS server is a pure TLS server (e.g. HTTPS) that only speaks TLS, 2539If your TLS server is a pure TLS server (e.g. HTTPS) that only speaks TLS,
2165simply connect to it and then create the AnyEvent::Handle with the C<tls> 2540connect to it and then create the AnyEvent::Handle with the C<tls>
2166parameter: 2541parameter:
2167 2542
2168 tcp_connect $host, $port, sub { 2543 tcp_connect $host, $port, sub {
2169 my ($fh) = @_; 2544 my ($fh) = @_;
2170 2545
… …
2244When you have intermediate CA certificates that your clients might not 2619When you have intermediate CA certificates that your clients might not
2245know about, just append them to the C<cert_file>. 2620know about, just append them to the C<cert_file>.
2246 2621
2247=back 2622=back
2248 2623
2249
2250=head1 SUBCLASSING AnyEvent::Handle 2624=head1 SUBCLASSING AnyEvent::Handle
2251 2625
2252In many cases, you might want to subclass AnyEvent::Handle. 2626In many cases, you might want to subclass AnyEvent::Handle.
2253 2627
2254To make this easier, a given version of AnyEvent::Handle uses these 2628To make this easier, a given version of AnyEvent::Handle uses these
… …
2270 2644
2271=item * all members not documented here and not prefixed with an underscore 2645=item * all members not documented here and not prefixed with an underscore
2272are free to use in subclasses. 2646are free to use in subclasses.
2273 2647
2274Of course, new versions of AnyEvent::Handle may introduce more "public" 2648Of course, new versions of AnyEvent::Handle may introduce more "public"
2275member variables, but thats just life, at least it is documented. 2649member variables, but that's just life. At least it is documented.
2276 2650
2277=back 2651=back
2278 2652
2279=head1 AUTHOR 2653=head1 AUTHOR
2280 2654
2281Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>. 2655Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>.
2282 2656
2283=cut 2657=cut
2284 2658
22851; # End of AnyEvent::Handle 26591
2660

Diff Legend

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