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.88 by root, Thu Aug 21 23:48:35 2008 UTC vs.
Revision 1.228 by root, Mon Feb 6 00:17:26 2012 UTC

1package AnyEvent::Handle;
2
3no warnings;
4use strict qw(subs vars);
5
6use AnyEvent ();
7use AnyEvent::Util qw(WSAEWOULDBLOCK);
8use Scalar::Util ();
9use Carp ();
10use Fcntl ();
11use Errno qw(EAGAIN EINTR);
12
13=head1 NAME 1=head1 NAME
14 2
15AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent 3AnyEvent::Handle - non-blocking I/O on streaming handles via AnyEvent
16
17=cut
18
19our $VERSION = 4.233;
20 4
21=head1 SYNOPSIS 5=head1 SYNOPSIS
22 6
23 use AnyEvent; 7 use AnyEvent;
24 use AnyEvent::Handle; 8 use AnyEvent::Handle;
25 9
26 my $cv = AnyEvent->condvar; 10 my $cv = AnyEvent->condvar;
27 11
28 my $handle = 12 my $hdl; $hdl = new AnyEvent::Handle
29 AnyEvent::Handle->new (
30 fh => \*STDIN, 13 fh => \*STDIN,
31 on_eof => sub { 14 on_error => sub {
32 $cv->broadcast; 15 my ($hdl, $fatal, $msg) = @_;
33 }, 16 AE::log error => "got error $msg\n";
17 $hdl->destroy;
18 $cv->send;
34 ); 19 };
35 20
36 # send some request line 21 # send some request line
37 $handle->push_write ("getinfo\015\012"); 22 $hdl->push_write ("getinfo\015\012");
38 23
39 # read the response line 24 # read the response line
40 $handle->push_read (line => sub { 25 $hdl->push_read (line => sub {
41 my ($handle, $line) = @_; 26 my ($hdl, $line) = @_;
42 warn "read line <$line>\n"; 27 say "got line <$line>";
43 $cv->send; 28 $cv->send;
44 }); 29 });
45 30
46 $cv->recv; 31 $cv->recv;
47 32
48=head1 DESCRIPTION 33=head1 DESCRIPTION
49 34
50This 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
51filehandles. For utility functions for doing non-blocking connects and accepts 36stream-based filehandles (sockets, pipes, and other stream things).
52on sockets see L<AnyEvent::Util>.
53 37
54The L<AnyEvent::Intro> tutorial contains some well-documented 38The L<AnyEvent::Intro> tutorial contains some well-documented
55AnyEvent::Handle examples. 39AnyEvent::Handle examples.
56 40
57In the following, when the documentation refers to of "bytes" then this 41In the following, where the documentation refers to "bytes", it means
58means characters. As sysread and syswrite are used for all I/O, their 42characters. As sysread and syswrite are used for all I/O, their
59treatment of characters applies to this module as well. 43treatment of characters applies to this module as well.
44
45At the very minimum, you should specify C<fh> or C<connect>, and the
46C<on_error> callback.
60 47
61All callbacks will be invoked with the handle object as their first 48All callbacks will be invoked with the handle object as their first
62argument. 49argument.
63 50
51=cut
52
53package AnyEvent::Handle;
54
55use Scalar::Util ();
56use List::Util ();
57use Carp ();
58use Errno qw(EAGAIN EINTR);
59
60use AnyEvent (); BEGIN { AnyEvent::common_sense }
61use AnyEvent::Util qw(WSAEWOULDBLOCK);
62
63our $VERSION = $AnyEvent::VERSION;
64
65sub _load_func($) {
66 my $func = $_[0];
67
68 unless (defined &$func) {
69 my $pkg = $func;
70 do {
71 $pkg =~ s/::[^:]+$//
72 or return;
73 eval "require $pkg";
74 } until defined &$func;
75 }
76
77 \&$func
78}
79
80sub MAX_READ_SIZE() { 131072 }
81
64=head1 METHODS 82=head1 METHODS
65 83
66=over 4 84=over 4
67 85
68=item B<new (%args)> 86=item $handle = B<new> AnyEvent::Handle fh => $filehandle, key => value...
69 87
70The constructor supports these arguments (all as key => value pairs). 88The constructor supports these arguments (all as C<< key => value >> pairs).
71 89
72=over 4 90=over 4
73 91
74=item fh => $filehandle [MANDATORY] 92=item fh => $filehandle [C<fh> or C<connect> MANDATORY]
75 93
76The filehandle this L<AnyEvent::Handle> object will operate on. 94The filehandle this L<AnyEvent::Handle> object will operate on.
77
78NOTE: The filehandle will be set to non-blocking mode (using 95NOTE: The filehandle will be set to non-blocking mode (using
79C<AnyEvent::Util::fh_nonblocking>) by the constructor and needs to stay in 96C<AnyEvent::Util::fh_nonblocking>) by the constructor and needs to stay in
80that mode. 97that mode.
81 98
99=item connect => [$host, $service] [C<fh> or C<connect> MANDATORY]
100
101Try to connect to the specified host and service (port), using
102C<AnyEvent::Socket::tcp_connect>. The C<$host> additionally becomes the
103default C<peername>.
104
105You have to specify either this parameter, or C<fh>, above.
106
107It is possible to push requests on the read and write queues, and modify
108properties of the stream, even while AnyEvent::Handle is connecting.
109
110When this parameter is specified, then the C<on_prepare>,
111C<on_connect_error> and C<on_connect> callbacks will be called under the
112appropriate circumstances:
113
114=over 4
115
82=item on_eof => $cb->($handle) 116=item on_prepare => $cb->($handle)
83 117
84Set the callback to be called when an end-of-file condition is detected, 118This (rarely used) callback is called before a new connection is
85i.e. in the case of a socket, when the other side has closed the 119attempted, but after the file handle has been created (you can access that
86connection cleanly. 120file handle via C<< $handle->{fh} >>). It could be used to prepare the
121file handle with parameters required for the actual connect (as opposed to
122settings that can be changed when the connection is already established).
87 123
88For sockets, this just means that the other side has stopped sending data, 124The return value of this callback should be the connect timeout value in
89you can still try to write data, and, in fact, one can return from the eof 125seconds (or C<0>, or C<undef>, or the empty list, to indicate that the
90callback and continue writing data, as only the read part has been shut 126default timeout is to be used).
91down.
92 127
93While not mandatory, it is I<highly> recommended to set an eof callback, 128=item on_connect => $cb->($handle, $host, $port, $retry->())
94otherwise you might end up with a closed socket while you are still
95waiting for data.
96 129
97If an EOF condition has been detected but no C<on_eof> callback has been 130This callback is called when a connection has been successfully established.
98set, then a fatal error will be raised with C<$!> set to <0>.
99 131
132The peer's numeric host and port (the socket peername) are passed as
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.
136
137It is not allowed to use the read or write queues while the handle object
138is connecting.
139
140If, for some reason, the handle is not acceptable, calling C<$retry> will
141continue with the next connection target (in case of multi-homed hosts or
142SRV records there can be multiple connection endpoints). The C<$retry>
143callback can be invoked after the connect callback returns, i.e. one can
144start a handshake and then decide to retry with the next host if the
145handshake fails.
146
147In most cases, you should ignore the C<$retry> parameter.
148
149=item on_connect_error => $cb->($handle, $message)
150
151This callback is called when the connection could not be
152established. C<$!> will contain the relevant error code, and C<$message> a
153message describing it (usually the same as C<"$!">).
154
155If this callback isn't specified, then C<on_error> will be called with a
156fatal error instead.
157
158=back
159
100=item on_error => $cb->($handle, $fatal) 160=item on_error => $cb->($handle, $fatal, $message)
101 161
102This is the error callback, which is called when, well, some error 162This is the error callback, which is called when, well, some error
103occured, such as not being able to resolve the hostname, failure to 163occured, such as not being able to resolve the hostname, failure to
104connect or a read error. 164connect, or a read error.
105 165
106Some 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
107fatal errors the handle object will be shut down and will not be usable 167fatal errors the handle object will be destroyed (by a call to C<< ->
108(but you are free to look at the current C<< ->rbuf >>). Examples of fatal 168destroy >>) after invoking the error callback (which means you are free to
109errors are an EOF condition with active (but unsatisifable) read watchers 169examine the handle object). Examples of fatal errors are an EOF condition
110(C<EPIPE>) or I/O errors. 170with active (but unsatisfiable) read watchers (C<EPIPE>) or I/O errors. In
171cases where the other side can close the connection at will, it is
172often easiest to not report C<EPIPE> errors in this callback.
111 173
174AnyEvent::Handle tries to find an appropriate error code for you to check
175against, but in some cases (TLS errors), this does not work well. It is
176recommended to always output the C<$message> argument in human-readable
177error messages (it's usually the same as C<"$!">).
178
112Non-fatal errors can be retried by simply returning, but it is recommended 179Non-fatal errors can be retried by returning, but it is recommended
113to simply ignore this parameter and instead abondon the handle object 180to simply ignore this parameter and instead abondon the handle object
114when this callback is invoked. Examples of non-fatal errors are timeouts 181when this callback is invoked. Examples of non-fatal errors are timeouts
115C<ETIMEDOUT>) or badly-formatted data (C<EBADMSG>). 182C<ETIMEDOUT>) or badly-formatted data (C<EBADMSG>).
116 183
117On callback entrance, the value of C<$!> contains the operating system 184On entry to the callback, the value of C<$!> contains the operating
118error (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT> or C<EBADMSG>). 185system error code (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT>, C<EBADMSG> or
186C<EPROTO>).
119 187
120While not mandatory, it is I<highly> recommended to set this callback, as 188While not mandatory, it is I<highly> recommended to set this callback, as
121you will not be notified of errors otherwise. The default simply calls 189you will not be notified of errors otherwise. The default just calls
122C<croak>. 190C<croak>.
123 191
124=item on_read => $cb->($handle) 192=item on_read => $cb->($handle)
125 193
126This sets the default read callback, which is called when data arrives 194This sets the default read callback, which is called when data arrives
127and no read request is in the queue (unlike read queue callbacks, this 195and no read request is in the queue (unlike read queue callbacks, this
128callback will only be called when at least one octet of data is in the 196callback will only be called when at least one octet of data is in the
129read buffer). 197read buffer).
130 198
131To access (and remove data from) the read buffer, use the C<< ->rbuf >> 199To access (and remove data from) the read buffer, use the C<< ->rbuf >>
132method or access the C<$handle->{rbuf}> member directly. 200method or access the C<< $handle->{rbuf} >> member directly. Note that you
201must not enlarge or modify the read buffer, you can only remove data at
202the beginning from it.
133 203
204You can also call C<< ->push_read (...) >> or any other function that
205modifies the read queue. Or do both. Or ...
206
134When an EOF condition is detected then AnyEvent::Handle will first try to 207When an EOF condition is detected, AnyEvent::Handle will first try to
135feed all the remaining data to the queued callbacks and C<on_read> before 208feed all the remaining data to the queued callbacks and C<on_read> before
136calling the C<on_eof> callback. If no progress can be made, then a fatal 209calling the C<on_eof> callback. If no progress can be made, then a fatal
137error will be raised (with C<$!> set to C<EPIPE>). 210error will be raised (with C<$!> set to C<EPIPE>).
138 211
212Note that, unlike requests in the read queue, an C<on_read> callback
213doesn't mean you I<require> some data: if there is an EOF and there
214are outstanding read requests then an error will be flagged. With an
215C<on_read> callback, the C<on_eof> callback will be invoked.
216
217=item on_eof => $cb->($handle)
218
219Set the callback to be called when an end-of-file condition is detected,
220i.e. in the case of a socket, when the other side has closed the
221connection cleanly, and there are no outstanding read requests in the
222queue (if there are read requests, then an EOF counts as an unexpected
223connection close and will be flagged as an error).
224
225For sockets, this just means that the other side has stopped sending data,
226you can still try to write data, and, in fact, one can return from the EOF
227callback and continue writing data, as only the read part has been shut
228down.
229
230If an EOF condition has been detected but no C<on_eof> callback has been
231set, then a fatal error will be raised with C<$!> set to <0>.
232
139=item on_drain => $cb->($handle) 233=item on_drain => $cb->($handle)
140 234
141This sets the callback that is called when the write buffer becomes empty 235This sets the callback that is called when the write buffer becomes empty
142(or when the callback is set and the buffer is empty already). 236(or immediately if the buffer is empty already).
143 237
144To append to the write buffer, use the C<< ->push_write >> method. 238To append to the write buffer, use the C<< ->push_write >> method.
145 239
146This callback is useful when you don't want to put all of your write data 240This callback is useful when you don't want to put all of your write data
147into the queue at once, for example, when you want to write the contents 241into the queue at once, for example, when you want to write the contents
149memory and push it into the queue, but instead only read more data from 243memory and push it into the queue, but instead only read more data from
150the file when the write queue becomes empty. 244the file when the write queue becomes empty.
151 245
152=item timeout => $fractional_seconds 246=item timeout => $fractional_seconds
153 247
248=item rtimeout => $fractional_seconds
249
250=item wtimeout => $fractional_seconds
251
154If non-zero, then this enables an "inactivity" timeout: whenever this many 252If non-zero, then these enables an "inactivity" timeout: whenever this
155seconds pass without a successful read or write on the underlying file 253many seconds pass without a successful read or write on the underlying
156handle, the C<on_timeout> callback will be invoked (and if that one is 254file handle (or a call to C<timeout_reset>), the C<on_timeout> callback
157missing, a non-fatal C<ETIMEDOUT> error will be raised). 255will be invoked (and if that one is missing, a non-fatal C<ETIMEDOUT>
256error will be raised).
158 257
258There are three variants of the timeouts that work independently of each
259other, for both read and write (triggered when nothing was read I<OR>
260written), just read (triggered when nothing was read), and just write:
261C<timeout>, C<rtimeout> and C<wtimeout>, with corresponding callbacks
262C<on_timeout>, C<on_rtimeout> and C<on_wtimeout>, and reset functions
263C<timeout_reset>, C<rtimeout_reset>, and C<wtimeout_reset>.
264
159Note that timeout processing is also active when you currently do not have 265Note that timeout processing is active even when you do not have any
160any outstanding read or write requests: If you plan to keep the connection 266outstanding read or write requests: If you plan to keep the connection
161idle then you should disable the timout temporarily or ignore the timeout 267idle then you should disable the timeout temporarily or ignore the
162in the C<on_timeout> callback, in which case AnyEvent::Handle will simply 268timeout in the corresponding C<on_timeout> callback, in which case
163restart the timeout. 269AnyEvent::Handle will simply restart the timeout.
164 270
165Zero (the default) disables this timeout. 271Zero (the default) disables the corresponding timeout.
166 272
167=item on_timeout => $cb->($handle) 273=item on_timeout => $cb->($handle)
274
275=item on_rtimeout => $cb->($handle)
276
277=item on_wtimeout => $cb->($handle)
168 278
169Called whenever the inactivity timeout passes. If you return from this 279Called whenever the inactivity timeout passes. If you return from this
170callback, then the timeout will be reset as if some activity had happened, 280callback, then the timeout will be reset as if some activity had happened,
171so this condition is not fatal in any way. 281so this condition is not fatal in any way.
172 282
180be configured to accept only so-and-so much data that it cannot act on 290be configured to accept only so-and-so much data that it cannot act on
181(for example, when expecting a line, an attacker could send an unlimited 291(for example, when expecting a line, an attacker could send an unlimited
182amount of data without a callback ever being called as long as the line 292amount of data without a callback ever being called as long as the line
183isn't finished). 293isn't finished).
184 294
295=item wbuf_max => <bytes>
296
297If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>)
298when the write buffer ever (strictly) exceeds this size. This is useful to
299avoid some forms of denial-of-service attacks.
300
301Although the units of this parameter is bytes, this is the I<raw> number
302of bytes not yet accepted by the kernel. This can make a difference when
303you e.g. use TLS, as TLS typically makes your write data larger (but it
304can also make it smaller due to compression).
305
306As an example of when this limit is useful, take a chat server that sends
307chat messages to a client. If the client does not read those in a timely
308manner then the send buffer in the server would grow unbounded.
309
185=item autocork => <boolean> 310=item autocork => <boolean>
186 311
187When disabled (the default), then C<push_write> will try to immediately 312When disabled (the default), C<push_write> will try to immediately
188write the data to the handle, if possible. This avoids having to register 313write the data to the handle if possible. This avoids having to register
189a write watcher and wait for the next event loop iteration, but can 314a write watcher and wait for the next event loop iteration, but can
190be inefficient if you write multiple small chunks (on the wire, this 315be inefficient if you write multiple small chunks (on the wire, this
191disadvantage is usually avoided by your kernel's nagle algorithm, see 316disadvantage is usually avoided by your kernel's nagle algorithm, see
192C<no_delay>, but this option can save costly syscalls). 317C<no_delay>, but this option can save costly syscalls).
193 318
194When enabled, then writes will always be queued till the next event loop 319When enabled, writes will always be queued till the next event loop
195iteration. This is efficient when you do many small writes per iteration, 320iteration. This is efficient when you do many small writes per iteration,
196but less efficient when you do a single write only per iteration (or when 321but less efficient when you do a single write only per iteration (or when
197the write buffer often is full). It also increases write latency. 322the write buffer often is full). It also increases write latency.
198 323
199=item no_delay => <boolean> 324=item no_delay => <boolean>
203the Nagle algorithm, and usually it is beneficial. 328the Nagle algorithm, and usually it is beneficial.
204 329
205In some situations you want as low a delay as possible, which can be 330In some situations you want as low a delay as possible, which can be
206accomplishd by setting this option to a true value. 331accomplishd by setting this option to a true value.
207 332
208The default is your opertaing system's default behaviour (most likely 333The default is your operating system's default behaviour (most likely
209enabled), this option explicitly enables or disables it, if possible. 334enabled). This option explicitly enables or disables it, if possible.
335
336=item keepalive => <boolean>
337
338Enables (default disable) the SO_KEEPALIVE option on the stream socket:
339normally, TCP connections have no time-out once established, so TCP
340connections, once established, can stay alive forever even when the other
341side has long gone. TCP keepalives are a cheap way to take down long-lived
342TCP connections when the other side becomes unreachable. While the default
343is OS-dependent, TCP keepalives usually kick in after around two hours,
344and, if the other side doesn't reply, take down the TCP connection some 10
345to 15 minutes later.
346
347It is harmless to specify this option for file handles that do not support
348keepalives, and enabling it on connections that are potentially long-lived
349is usually a good idea.
350
351=item oobinline => <boolean>
352
353BSD majorly fucked up the implementation of TCP urgent data. The result
354is that almost no OS implements TCP according to the specs, and every OS
355implements it slightly differently.
356
357If you want to handle TCP urgent data, then setting this flag (the default
358is enabled) gives you the most portable way of getting urgent data, by
359putting it into the stream.
360
361Since BSD emulation of OOB data on top of TCP's urgent data can have
362security implications, AnyEvent::Handle sets this flag automatically
363unless explicitly specified. Note that setting this flag after
364establishing a connection I<may> be a bit too late (data loss could
365already have occured on BSD systems), but at least it will protect you
366from most attacks.
210 367
211=item read_size => <bytes> 368=item read_size => <bytes>
212 369
213The default read block size (the amount of bytes this module will 370The initial read block size, the number of bytes this module will try
214try to read during each loop iteration, which affects memory 371to read during each loop iteration. Each handle object will consume
215requirements). Default: C<8192>. 372at least this amount of memory for the read buffer as well, so when
373handling many connections watch out for memory requirements). See also
374C<max_read_size>. Default: C<2048>.
375
376=item max_read_size => <bytes>
377
378The maximum read buffer size used by the dynamic adjustment
379algorithm: Each time AnyEvent::Handle can read C<read_size> bytes in
380one go it will double C<read_size> up to the maximum given by this
381option. Default: C<131072> or C<read_size>, whichever is higher.
216 382
217=item low_water_mark => <bytes> 383=item low_water_mark => <bytes>
218 384
219Sets the amount of bytes (default: C<0>) that make up an "empty" write 385Sets the number of bytes (default: C<0>) that make up an "empty" write
220buffer: If the write reaches this size or gets even samller it is 386buffer: If the buffer reaches this size or gets even samller it is
221considered empty. 387considered empty.
222 388
223Sometimes it can be beneficial (for performance reasons) to add data to 389Sometimes it can be beneficial (for performance reasons) to add data to
224the write buffer before it is fully drained, but this is a rare case, as 390the write buffer before it is fully drained, but this is a rare case, as
225the operating system kernel usually buffers data as well, so the default 391the operating system kernel usually buffers data as well, so the default
226is good in almost all cases. 392is good in almost all cases.
227 393
228=item linger => <seconds> 394=item linger => <seconds>
229 395
230If non-zero (default: C<3600>), then the destructor of the 396If this is non-zero (default: C<3600>), the destructor of the
231AnyEvent::Handle object will check whether there is still outstanding 397AnyEvent::Handle object will check whether there is still outstanding
232write data and will install a watcher that will write this data to the 398write data and will install a watcher that will write this data to the
233socket. No errors will be reported (this mostly matches how the operating 399socket. No errors will be reported (this mostly matches how the operating
234system treats outstanding data at socket close time). 400system treats outstanding data at socket close time).
235 401
236This will not work for partial TLS data that could not be encoded 402This will not work for partial TLS data that could not be encoded
237yet. This data will be lost. 403yet. This data will be lost. Calling the C<stoptls> method in time might
404help.
405
406=item peername => $string
407
408A string used to identify the remote site - usually the DNS hostname
409(I<not> IDN!) used to create the connection, rarely the IP address.
410
411Apart from being useful in error messages, this string is also used in TLS
412peername verification (see C<verify_peername> in L<AnyEvent::TLS>). This
413verification will be skipped when C<peername> is not specified or is
414C<undef>.
238 415
239=item tls => "accept" | "connect" | Net::SSLeay::SSL object 416=item tls => "accept" | "connect" | Net::SSLeay::SSL object
240 417
241When this parameter is given, it enables TLS (SSL) mode, that means 418When this parameter is given, it enables TLS (SSL) mode, that means
242AnyEvent will start a TLS handshake as soon as the conenction has been 419AnyEvent will start a TLS handshake as soon as the connection has been
243established and will transparently encrypt/decrypt data afterwards. 420established and will transparently encrypt/decrypt data afterwards.
421
422All TLS protocol errors will be signalled as C<EPROTO>, with an
423appropriate error message.
244 424
245TLS mode requires Net::SSLeay to be installed (it will be loaded 425TLS mode requires Net::SSLeay to be installed (it will be loaded
246automatically when you try to create a TLS handle): this module doesn't 426automatically when you try to create a TLS handle): this module doesn't
247have a dependency on that module, so if your module requires it, you have 427have a dependency on that module, so if your module requires it, you have
248to add the dependency yourself. 428to add the dependency yourself.
252mode. 432mode.
253 433
254You can also provide your own TLS connection object, but you have 434You can also provide your own TLS connection object, but you have
255to make sure that you call either C<Net::SSLeay::set_connect_state> 435to make sure that you call either C<Net::SSLeay::set_connect_state>
256or C<Net::SSLeay::set_accept_state> on it before you pass it to 436or C<Net::SSLeay::set_accept_state> on it before you pass it to
257AnyEvent::Handle. 437AnyEvent::Handle. Also, this module will take ownership of this connection
438object.
258 439
440At some future point, AnyEvent::Handle might switch to another TLS
441implementation, then the option to use your own session object will go
442away.
443
444B<IMPORTANT:> since Net::SSLeay "objects" are really only integers,
445passing in the wrong integer will lead to certain crash. This most often
446happens when one uses a stylish C<< tls => 1 >> and is surprised about the
447segmentation fault.
448
259See the C<< ->starttls >> method for when need to start TLS negotiation later. 449Use the C<< ->starttls >> method if you need to start TLS negotiation later.
260 450
261=item tls_ctx => $ssl_ctx 451=item tls_ctx => $anyevent_tls
262 452
263Use the given C<Net::SSLeay::CTX> object to create the new TLS connection 453Use the given C<AnyEvent::TLS> object to create the new TLS connection
264(unless a connection object was specified directly). If this parameter is 454(unless a connection object was specified directly). If this
265missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>. 455parameter is missing (or C<undef>), then AnyEvent::Handle will use
456C<AnyEvent::Handle::TLS_CTX>.
457
458Instead of an object, you can also specify a hash reference with C<< key
459=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a
460new TLS context object.
461
462=item on_starttls => $cb->($handle, $success[, $error_message])
463
464This callback will be invoked when the TLS/SSL handshake has finished. If
465C<$success> is true, then the TLS handshake succeeded, otherwise it failed
466(C<on_stoptls> will not be called in this case).
467
468The session in C<< $handle->{tls} >> can still be examined in this
469callback, even when the handshake was not successful.
470
471TLS handshake failures will not cause C<on_error> to be invoked when this
472callback is in effect, instead, the error message will be passed to C<on_starttls>.
473
474Without this callback, handshake failures lead to C<on_error> being
475called as usual.
476
477Note that you cannot just call C<starttls> again in this callback. If you
478need to do that, start an zero-second timer instead whose callback can
479then call C<< ->starttls >> again.
480
481=item on_stoptls => $cb->($handle)
482
483When a SSLv3/TLS shutdown/close notify/EOF is detected and this callback is
484set, then it will be invoked after freeing the TLS session. If it is not,
485then a TLS shutdown condition will be treated like a normal EOF condition
486on the handle.
487
488The session in C<< $handle->{tls} >> can still be examined in this
489callback.
490
491This callback will only be called on TLS shutdowns, not when the
492underlying handle signals EOF.
266 493
267=item json => JSON or JSON::XS object 494=item json => JSON or JSON::XS object
268 495
269This is the json coder object used by the C<json> read and write types. 496This is the json coder object used by the C<json> read and write types.
270 497
273texts. 500texts.
274 501
275Note that you are responsible to depend on the JSON module if you want to 502Note that you are responsible to depend on the JSON module if you want to
276use this functionality, as AnyEvent does not have a dependency itself. 503use this functionality, as AnyEvent does not have a dependency itself.
277 504
278=item filter_r => $cb
279
280=item filter_w => $cb
281
282These exist, but are undocumented at this time. (They are used internally
283by the TLS code).
284
285=back 505=back
286 506
287=cut 507=cut
288 508
289sub new { 509sub new {
290 my $class = shift; 510 my $class = shift;
291
292 my $self = bless { @_ }, $class; 511 my $self = bless { @_ }, $class;
293 512
294 $self->{fh} or Carp::croak "mandatory argument fh is missing"; 513 if ($self->{fh}) {
514 $self->_start;
515 return unless $self->{fh}; # could be gone by now
516
517 } elsif ($self->{connect}) {
518 require AnyEvent::Socket;
519
520 $self->{peername} = $self->{connect}[0]
521 unless exists $self->{peername};
522
523 $self->{_skip_drain_rbuf} = 1;
524
525 {
526 Scalar::Util::weaken (my $self = $self);
527
528 $self->{_connect} =
529 AnyEvent::Socket::tcp_connect (
530 $self->{connect}[0],
531 $self->{connect}[1],
532 sub {
533 my ($fh, $host, $port, $retry) = @_;
534
535 delete $self->{_connect}; # no longer needed
536
537 if ($fh) {
538 $self->{fh} = $fh;
539
540 delete $self->{_skip_drain_rbuf};
541 $self->_start;
542
543 $self->{on_connect}
544 and $self->{on_connect}($self, $host, $port, sub {
545 delete @$self{qw(fh _tw _rtw _wtw _ww _rw _eof _queue rbuf _wbuf tls _tls_rbuf _tls_wbuf)};
546 $self->{_skip_drain_rbuf} = 1;
547 &$retry;
548 });
549
550 } else {
551 if ($self->{on_connect_error}) {
552 $self->{on_connect_error}($self, "$!");
553 $self->destroy if $self;
554 } else {
555 $self->_error ($!, 1);
556 }
557 }
558 },
559 sub {
560 local $self->{fh} = $_[0];
561
562 $self->{on_prepare}
563 ? $self->{on_prepare}->($self)
564 : ()
565 }
566 );
567 }
568
569 } else {
570 Carp::croak "AnyEvent::Handle: either an existing fh or the connect parameter must be specified";
571 }
572
573 $self
574}
575
576sub _start {
577 my ($self) = @_;
578
579 # too many clueless people try to use udp and similar sockets
580 # with AnyEvent::Handle, do them a favour.
581 my $type = getsockopt $self->{fh}, Socket::SOL_SOCKET (), Socket::SO_TYPE ();
582 Carp::croak "AnyEvent::Handle: only stream sockets supported, anything else will NOT work!"
583 if Socket::SOCK_STREAM () != (unpack "I", $type) && defined $type;
295 584
296 AnyEvent::Util::fh_nonblocking $self->{fh}, 1; 585 AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
297 586
298 if ($self->{tls}) { 587 $self->{_activity} =
299 require Net::SSLeay; 588 $self->{_ractivity} =
589 $self->{_wactivity} = AE::now;
590
591 $self->{read_size} ||= 2048;
592 $self->{max_read_size} = $self->{read_size}
593 if $self->{read_size} > ($self->{max_read_size} || MAX_READ_SIZE);
594
595 $self->timeout (delete $self->{timeout} ) if $self->{timeout};
596 $self->rtimeout (delete $self->{rtimeout} ) if $self->{rtimeout};
597 $self->wtimeout (delete $self->{wtimeout} ) if $self->{wtimeout};
598
599 $self->no_delay (delete $self->{no_delay} ) if exists $self->{no_delay} && $self->{no_delay};
600 $self->keepalive (delete $self->{keepalive}) if exists $self->{keepalive} && $self->{keepalive};
601
602 $self->oobinline (exists $self->{oobinline} ? delete $self->{oobinline} : 1);
603
300 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx}); 604 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx})
301 } 605 if $self->{tls};
302 606
303 $self->{_activity} = AnyEvent->now;
304 $self->_timeout;
305
306 $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain}; 607 $self->on_drain (delete $self->{on_drain} ) if $self->{on_drain};
307 $self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay};
308 608
309 $self->start_read 609 $self->start_read
310 if $self->{on_read}; 610 if $self->{on_read} || @{ $self->{_queue} };
311 611
312 $self 612 $self->_drain_wbuf;
313}
314
315sub _shutdown {
316 my ($self) = @_;
317
318 delete $self->{_tw};
319 delete $self->{_rw};
320 delete $self->{_ww};
321 delete $self->{fh};
322
323 $self->stoptls;
324
325 delete $self->{on_read};
326 delete $self->{_queue};
327} 613}
328 614
329sub _error { 615sub _error {
330 my ($self, $errno, $fatal) = @_; 616 my ($self, $errno, $fatal, $message) = @_;
331
332 $self->_shutdown
333 if $fatal;
334 617
335 $! = $errno; 618 $! = $errno;
619 $message ||= "$!";
336 620
337 if ($self->{on_error}) { 621 if ($self->{on_error}) {
338 $self->{on_error}($self, $fatal); 622 $self->{on_error}($self, $fatal, $message);
339 } else { 623 $self->destroy if $fatal;
624 } elsif ($self->{fh} || $self->{connect}) {
625 $self->destroy;
340 Carp::croak "AnyEvent::Handle uncaught error: $!"; 626 Carp::croak "AnyEvent::Handle uncaught error: $message";
341 } 627 }
342} 628}
343 629
344=item $fh = $handle->fh 630=item $fh = $handle->fh
345 631
369 $_[0]{on_eof} = $_[1]; 655 $_[0]{on_eof} = $_[1];
370} 656}
371 657
372=item $handle->on_timeout ($cb) 658=item $handle->on_timeout ($cb)
373 659
374Replace the current C<on_timeout> callback, or disables the callback (but 660=item $handle->on_rtimeout ($cb)
375not the timeout) if C<$cb> = C<undef>. See the C<timeout> constructor
376argument and method.
377 661
378=cut 662=item $handle->on_wtimeout ($cb)
379 663
380sub on_timeout { 664Replace the current C<on_timeout>, C<on_rtimeout> or C<on_wtimeout>
381 $_[0]{on_timeout} = $_[1]; 665callback, or disables the callback (but not the timeout) if C<$cb> =
382} 666C<undef>. See the C<timeout> constructor argument and method.
667
668=cut
669
670# see below
383 671
384=item $handle->autocork ($boolean) 672=item $handle->autocork ($boolean)
385 673
386Enables or disables the current autocork behaviour (see C<autocork> 674Enables or disables the current autocork behaviour (see C<autocork>
387constructor argument). 675constructor argument). Changes will only take effect on the next write.
388 676
389=cut 677=cut
678
679sub autocork {
680 $_[0]{autocork} = $_[1];
681}
390 682
391=item $handle->no_delay ($boolean) 683=item $handle->no_delay ($boolean)
392 684
393Enables or disables the C<no_delay> setting (see constructor argument of 685Enables or disables the C<no_delay> setting (see constructor argument of
394the same name for details). 686the same name for details).
396=cut 688=cut
397 689
398sub no_delay { 690sub no_delay {
399 $_[0]{no_delay} = $_[1]; 691 $_[0]{no_delay} = $_[1];
400 692
693 setsockopt $_[0]{fh}, Socket::IPPROTO_TCP (), Socket::TCP_NODELAY (), int $_[1]
694 if $_[0]{fh};
695}
696
697=item $handle->keepalive ($boolean)
698
699Enables or disables the C<keepalive> setting (see constructor argument of
700the same name for details).
701
702=cut
703
704sub keepalive {
705 $_[0]{keepalive} = $_[1];
706
401 eval { 707 eval {
402 local $SIG{__DIE__}; 708 local $SIG{__DIE__};
403 setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1]; 709 setsockopt $_[0]{fh}, Socket::SOL_SOCKET (), Socket::SO_KEEPALIVE (), int $_[1]
710 if $_[0]{fh};
404 }; 711 };
405} 712}
406 713
714=item $handle->oobinline ($boolean)
715
716Enables or disables the C<oobinline> setting (see constructor argument of
717the same name for details).
718
719=cut
720
721sub oobinline {
722 $_[0]{oobinline} = $_[1];
723
724 eval {
725 local $SIG{__DIE__};
726 setsockopt $_[0]{fh}, Socket::SOL_SOCKET (), Socket::SO_OOBINLINE (), int $_[1]
727 if $_[0]{fh};
728 };
729}
730
731=item $handle->keepalive ($boolean)
732
733Enables or disables the C<keepalive> setting (see constructor argument of
734the same name for details).
735
736=cut
737
738sub keepalive {
739 $_[0]{keepalive} = $_[1];
740
741 eval {
742 local $SIG{__DIE__};
743 setsockopt $_[0]{fh}, Socket::SOL_SOCKET (), Socket::SO_KEEPALIVE (), int $_[1]
744 if $_[0]{fh};
745 };
746}
747
748=item $handle->on_starttls ($cb)
749
750Replace the current C<on_starttls> callback (see the C<on_starttls> constructor argument).
751
752=cut
753
754sub on_starttls {
755 $_[0]{on_starttls} = $_[1];
756}
757
758=item $handle->on_stoptls ($cb)
759
760Replace the current C<on_stoptls> callback (see the C<on_stoptls> constructor argument).
761
762=cut
763
764sub on_stoptls {
765 $_[0]{on_stoptls} = $_[1];
766}
767
768=item $handle->rbuf_max ($max_octets)
769
770Configures the C<rbuf_max> setting (C<undef> disables it).
771
772=item $handle->wbuf_max ($max_octets)
773
774Configures the C<wbuf_max> setting (C<undef> disables it).
775
776=cut
777
778sub rbuf_max {
779 $_[0]{rbuf_max} = $_[1];
780}
781
782sub wbuf_max {
783 $_[0]{wbuf_max} = $_[1];
784}
785
407############################################################################# 786#############################################################################
408 787
409=item $handle->timeout ($seconds) 788=item $handle->timeout ($seconds)
410 789
790=item $handle->rtimeout ($seconds)
791
792=item $handle->wtimeout ($seconds)
793
411Configures (or disables) the inactivity timeout. 794Configures (or disables) the inactivity timeout.
412 795
413=cut 796The timeout will be checked instantly, so this method might destroy the
797handle before it returns.
414 798
415sub timeout { 799=item $handle->timeout_reset
800
801=item $handle->rtimeout_reset
802
803=item $handle->wtimeout_reset
804
805Reset the activity timeout, as if data was received or sent.
806
807These methods are cheap to call.
808
809=cut
810
811for my $dir ("", "r", "w") {
812 my $timeout = "${dir}timeout";
813 my $tw = "_${dir}tw";
814 my $on_timeout = "on_${dir}timeout";
815 my $activity = "_${dir}activity";
816 my $cb;
817
818 *$on_timeout = sub {
819 $_[0]{$on_timeout} = $_[1];
820 };
821
822 *$timeout = sub {
416 my ($self, $timeout) = @_; 823 my ($self, $new_value) = @_;
417 824
825 $new_value >= 0
826 or Carp::croak "AnyEvent::Handle->$timeout called with negative timeout ($new_value), caught";
827
418 $self->{timeout} = $timeout; 828 $self->{$timeout} = $new_value;
419 $self->_timeout; 829 delete $self->{$tw}; &$cb;
420} 830 };
421 831
832 *{"${dir}timeout_reset"} = sub {
833 $_[0]{$activity} = AE::now;
834 };
835
836 # main workhorse:
422# reset the timeout watcher, as neccessary 837 # reset the timeout watcher, as neccessary
423# also check for time-outs 838 # also check for time-outs
424sub _timeout { 839 $cb = sub {
425 my ($self) = @_; 840 my ($self) = @_;
426 841
427 if ($self->{timeout}) { 842 if ($self->{$timeout} && $self->{fh}) {
428 my $NOW = AnyEvent->now; 843 my $NOW = AE::now;
429 844
430 # when would the timeout trigger? 845 # when would the timeout trigger?
431 my $after = $self->{_activity} + $self->{timeout} - $NOW; 846 my $after = $self->{$activity} + $self->{$timeout} - $NOW;
432 847
433 # now or in the past already? 848 # now or in the past already?
434 if ($after <= 0) { 849 if ($after <= 0) {
435 $self->{_activity} = $NOW; 850 $self->{$activity} = $NOW;
436 851
437 if ($self->{on_timeout}) { 852 if ($self->{$on_timeout}) {
438 $self->{on_timeout}($self); 853 $self->{$on_timeout}($self);
439 } else { 854 } else {
440 $self->_error (&Errno::ETIMEDOUT); 855 $self->_error (Errno::ETIMEDOUT);
856 }
857
858 # callback could have changed timeout value, optimise
859 return unless $self->{$timeout};
860
861 # calculate new after
862 $after = $self->{$timeout};
441 } 863 }
442 864
443 # callback could have changed timeout value, optimise 865 Scalar::Util::weaken $self;
444 return unless $self->{timeout}; 866 return unless $self; # ->error could have destroyed $self
445 867
446 # calculate new after 868 $self->{$tw} ||= AE::timer $after, 0, sub {
447 $after = $self->{timeout}; 869 delete $self->{$tw};
870 $cb->($self);
871 };
872 } else {
873 delete $self->{$tw};
448 } 874 }
449
450 Scalar::Util::weaken $self;
451 return unless $self; # ->error could have destroyed $self
452
453 $self->{_tw} ||= AnyEvent->timer (after => $after, cb => sub {
454 delete $self->{_tw};
455 $self->_timeout;
456 });
457 } else {
458 delete $self->{_tw};
459 } 875 }
460} 876}
461 877
462############################################################################# 878#############################################################################
463 879
479=item $handle->on_drain ($cb) 895=item $handle->on_drain ($cb)
480 896
481Sets the C<on_drain> callback or clears it (see the description of 897Sets the C<on_drain> callback or clears it (see the description of
482C<on_drain> in the constructor). 898C<on_drain> in the constructor).
483 899
900This method may invoke callbacks (and therefore the handle might be
901destroyed after it returns).
902
484=cut 903=cut
485 904
486sub on_drain { 905sub on_drain {
487 my ($self, $cb) = @_; 906 my ($self, $cb) = @_;
488 907
489 $self->{on_drain} = $cb; 908 $self->{on_drain} = $cb;
490 909
491 $cb->($self) 910 $cb->($self)
492 if $cb && $self->{low_water_mark} >= length $self->{wbuf}; 911 if $cb && $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf});
493} 912}
494 913
495=item $handle->push_write ($data) 914=item $handle->push_write ($data)
496 915
497Queues the given scalar to be written. You can push as much data as you 916Queues the given scalar to be written. You can push as much data as
498want (only limited by the available memory), as C<AnyEvent::Handle> 917you want (only limited by the available memory and C<wbuf_max>), as
499buffers it independently of the kernel. 918C<AnyEvent::Handle> buffers it independently of the kernel.
919
920This method may invoke callbacks (and therefore the handle might be
921destroyed after it returns).
500 922
501=cut 923=cut
502 924
503sub _drain_wbuf { 925sub _drain_wbuf {
504 my ($self) = @_; 926 my ($self) = @_;
508 Scalar::Util::weaken $self; 930 Scalar::Util::weaken $self;
509 931
510 my $cb = sub { 932 my $cb = sub {
511 my $len = syswrite $self->{fh}, $self->{wbuf}; 933 my $len = syswrite $self->{fh}, $self->{wbuf};
512 934
513 if ($len >= 0) { 935 if (defined $len) {
514 substr $self->{wbuf}, 0, $len, ""; 936 substr $self->{wbuf}, 0, $len, "";
515 937
516 $self->{_activity} = AnyEvent->now; 938 $self->{_activity} = $self->{_wactivity} = AE::now;
517 939
518 $self->{on_drain}($self) 940 $self->{on_drain}($self)
519 if $self->{low_water_mark} >= length $self->{wbuf} 941 if $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf})
520 && $self->{on_drain}; 942 && $self->{on_drain};
521 943
522 delete $self->{_ww} unless length $self->{wbuf}; 944 delete $self->{_ww} unless length $self->{wbuf};
523 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) { 945 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {
524 $self->_error ($!, 1); 946 $self->_error ($!, 1);
527 949
528 # try to write data immediately 950 # try to write data immediately
529 $cb->() unless $self->{autocork}; 951 $cb->() unless $self->{autocork};
530 952
531 # if still data left in wbuf, we need to poll 953 # if still data left in wbuf, we need to poll
532 $self->{_ww} = AnyEvent->io (fh => $self->{fh}, poll => "w", cb => $cb) 954 $self->{_ww} = AE::io $self->{fh}, 1, $cb
533 if length $self->{wbuf}; 955 if length $self->{wbuf};
956
957 if (
958 defined $self->{wbuf_max}
959 && $self->{wbuf_max} < length $self->{wbuf}
960 ) {
961 $self->_error (Errno::ENOSPC, 1), return;
962 }
534 }; 963 };
535} 964}
536 965
537our %WH; 966our %WH;
538 967
968# deprecated
539sub register_write_type($$) { 969sub register_write_type($$) {
540 $WH{$_[0]} = $_[1]; 970 $WH{$_[0]} = $_[1];
541} 971}
542 972
543sub push_write { 973sub push_write {
544 my $self = shift; 974 my $self = shift;
545 975
546 if (@_ > 1) { 976 if (@_ > 1) {
547 my $type = shift; 977 my $type = shift;
548 978
979 @_ = ($WH{$type} ||= _load_func "$type\::anyevent_write_type"
549 @_ = ($WH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_write") 980 or Carp::croak "unsupported/unloadable type '$type' passed to AnyEvent::Handle::push_write")
550 ->($self, @_); 981 ->($self, @_);
551 } 982 }
552 983
984 # we downgrade here to avoid hard-to-track-down bugs,
985 # and diagnose the problem earlier and better.
986
553 if ($self->{filter_w}) { 987 if ($self->{tls}) {
554 $self->{filter_w}($self, \$_[0]); 988 utf8::downgrade $self->{_tls_wbuf} .= $_[0];
989 &_dotls ($self) if $self->{fh};
555 } else { 990 } else {
556 $self->{wbuf} .= $_[0]; 991 utf8::downgrade $self->{wbuf} .= $_[0];
557 $self->_drain_wbuf; 992 $self->_drain_wbuf if $self->{fh};
558 } 993 }
559} 994}
560 995
561=item $handle->push_write (type => @args) 996=item $handle->push_write (type => @args)
562 997
563Instead of formatting your data yourself, you can also let this module do 998Instead of formatting your data yourself, you can also let this module
564the job by specifying a type and type-specific arguments. 999do the job by specifying a type and type-specific arguments. You
1000can also specify the (fully qualified) name of a package, in which
1001case AnyEvent tries to load the package and then expects to find the
1002C<anyevent_write_type> function inside (see "custom write types", below).
565 1003
566Predefined types are (if you have ideas for additional types, feel free to 1004Predefined types are (if you have ideas for additional types, feel free to
567drop by and tell us): 1005drop by and tell us):
568 1006
569=over 4 1007=over 4
576=cut 1014=cut
577 1015
578register_write_type netstring => sub { 1016register_write_type netstring => sub {
579 my ($self, $string) = @_; 1017 my ($self, $string) = @_;
580 1018
581 sprintf "%d:%s,", (length $string), $string 1019 (length $string) . ":$string,"
582}; 1020};
583 1021
584=item packstring => $format, $data 1022=item packstring => $format, $data
585 1023
586An octet string prefixed with an encoded length. The encoding C<$format> 1024An octet string prefixed with an encoded length. The encoding C<$format>
626Other languages could read single lines terminated by a newline and pass 1064Other languages could read single lines terminated by a newline and pass
627this line into their JSON decoder of choice. 1065this line into their JSON decoder of choice.
628 1066
629=cut 1067=cut
630 1068
1069sub json_coder() {
1070 eval { require JSON::XS; JSON::XS->new->utf8 }
1071 || do { require JSON; JSON->new->utf8 }
1072}
1073
631register_write_type json => sub { 1074register_write_type json => sub {
632 my ($self, $ref) = @_; 1075 my ($self, $ref) = @_;
633 1076
634 require JSON; 1077 my $json = $self->{json} ||= json_coder;
635 1078
636 $self->{json} ? $self->{json}->encode ($ref) 1079 $json->encode ($ref)
637 : JSON::encode_json ($ref)
638}; 1080};
639 1081
640=item storable => $reference 1082=item storable => $reference
641 1083
642Freezes the given reference using L<Storable> and writes it to the 1084Freezes the given reference using L<Storable> and writes it to the
645=cut 1087=cut
646 1088
647register_write_type storable => sub { 1089register_write_type storable => sub {
648 my ($self, $ref) = @_; 1090 my ($self, $ref) = @_;
649 1091
650 require Storable; 1092 require Storable unless $Storable::VERSION;
651 1093
652 pack "w/a*", Storable::nfreeze ($ref) 1094 pack "w/a*", Storable::nfreeze ($ref)
653}; 1095};
654 1096
655=back 1097=back
656 1098
657=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args) 1099=item $handle->push_shutdown
658 1100
659This function (not method) lets you add your own types to C<push_write>. 1101Sometimes you know you want to close the socket after writing your data
1102before it was actually written. One way to do that is to replace your
1103C<on_drain> handler by a callback that shuts down the socket (and set
1104C<low_water_mark> to C<0>). This method is a shorthand for just that, and
1105replaces the C<on_drain> callback with:
1106
1107 sub { shutdown $_[0]{fh}, 1 }
1108
1109This simply shuts down the write side and signals an EOF condition to the
1110the peer.
1111
1112You can rely on the normal read queue and C<on_eof> handling
1113afterwards. This is the cleanest way to close a connection.
1114
1115This method may invoke callbacks (and therefore the handle might be
1116destroyed after it returns).
1117
1118=cut
1119
1120sub push_shutdown {
1121 my ($self) = @_;
1122
1123 delete $self->{low_water_mark};
1124 $self->on_drain (sub { shutdown $_[0]{fh}, 1 });
1125}
1126
1127=item custom write types - Package::anyevent_write_type $handle, @args
1128
1129Instead of one of the predefined types, you can also specify the name of
1130a package. AnyEvent will try to load the package and then expects to find
1131a function named C<anyevent_write_type> inside. If it isn't found, it
1132progressively tries to load the parent package until it either finds the
1133function (good) or runs out of packages (bad).
1134
660Whenever the given C<type> is used, C<push_write> will invoke the code 1135Whenever the given C<type> is used, C<push_write> will the function with
661reference with the handle object and the remaining arguments. 1136the handle object and the remaining arguments.
662 1137
663The code reference is supposed to return a single octet string that will 1138The function is supposed to return a single octet string that will be
664be appended to the write buffer. 1139appended to the write buffer, so you can mentally treat this function as a
1140"arguments to on-the-wire-format" converter.
665 1141
666Note that this is a function, and all types registered this way will be 1142Example: implement a custom write type C<join> that joins the remaining
667global, so try to use unique names. 1143arguments using the first one.
1144
1145 $handle->push_write (My::Type => " ", 1,2,3);
1146
1147 # uses the following package, which can be defined in the "My::Type" or in
1148 # the "My" modules to be auto-loaded, or just about anywhere when the
1149 # My::Type::anyevent_write_type is defined before invoking it.
1150
1151 package My::Type;
1152
1153 sub anyevent_write_type {
1154 my ($handle, $delim, @args) = @_;
1155
1156 join $delim, @args
1157 }
668 1158
669=cut 1159=cut
670 1160
671############################################################################# 1161#############################################################################
672 1162
681ways, the "simple" way, using only C<on_read> and the "complex" way, using 1171ways, the "simple" way, using only C<on_read> and the "complex" way, using
682a queue. 1172a queue.
683 1173
684In the simple case, you just install an C<on_read> callback and whenever 1174In the simple case, you just install an C<on_read> callback and whenever
685new data arrives, it will be called. You can then remove some data (if 1175new data arrives, it will be called. You can then remove some data (if
686enough is there) from the read buffer (C<< $handle->rbuf >>). Or you cna 1176enough is there) from the read buffer (C<< $handle->rbuf >>). Or you can
687leave the data there if you want to accumulate more (e.g. when only a 1177leave the data there if you want to accumulate more (e.g. when only a
688partial message has been received so far). 1178partial message has been received so far), or change the read queue with
1179e.g. C<push_read>.
689 1180
690In the more complex case, you want to queue multiple callbacks. In this 1181In the more complex case, you want to queue multiple callbacks. In this
691case, AnyEvent::Handle will call the first queued callback each time new 1182case, AnyEvent::Handle will call the first queued callback each time new
692data arrives (also the first time it is queued) and removes it when it has 1183data arrives (also the first time it is queued) and remove it when it has
693done its job (see C<push_read>, below). 1184done its job (see C<push_read>, below).
694 1185
695This way you can, for example, push three line-reads, followed by reading 1186This way you can, for example, push three line-reads, followed by reading
696a chunk of data, and AnyEvent::Handle will execute them in order. 1187a chunk of data, and AnyEvent::Handle will execute them in order.
697 1188
754=cut 1245=cut
755 1246
756sub _drain_rbuf { 1247sub _drain_rbuf {
757 my ($self) = @_; 1248 my ($self) = @_;
758 1249
1250 # avoid recursion
1251 return if $self->{_skip_drain_rbuf};
759 local $self->{_in_drain} = 1; 1252 local $self->{_skip_drain_rbuf} = 1;
760
761 if (
762 defined $self->{rbuf_max}
763 && $self->{rbuf_max} < length $self->{rbuf}
764 ) {
765 $self->_error (&Errno::ENOSPC, 1), return;
766 }
767 1253
768 while () { 1254 while () {
1255 # we need to use a separate tls read buffer, as we must not receive data while
1256 # we are draining the buffer, and this can only happen with TLS.
1257 $self->{rbuf} .= delete $self->{_tls_rbuf}
1258 if exists $self->{_tls_rbuf};
1259
769 my $len = length $self->{rbuf}; 1260 my $len = length $self->{rbuf};
770 1261
771 if (my $cb = shift @{ $self->{_queue} }) { 1262 if (my $cb = shift @{ $self->{_queue} }) {
772 unless ($cb->($self)) { 1263 unless ($cb->($self)) {
773 if ($self->{_eof}) { 1264 # no progress can be made
774 # no progress can be made (not enough data and no data forthcoming) 1265 # (not enough data and no data forthcoming)
775 $self->_error (&Errno::EPIPE, 1), return; 1266 $self->_error (Errno::EPIPE, 1), return
776 } 1267 if $self->{_eof};
777 1268
778 unshift @{ $self->{_queue} }, $cb; 1269 unshift @{ $self->{_queue} }, $cb;
779 last; 1270 last;
780 } 1271 }
781 } elsif ($self->{on_read}) { 1272 } elsif ($self->{on_read}) {
788 && !@{ $self->{_queue} } # and the queue is still empty 1279 && !@{ $self->{_queue} } # and the queue is still empty
789 && $self->{on_read} # but we still have on_read 1280 && $self->{on_read} # but we still have on_read
790 ) { 1281 ) {
791 # no further data will arrive 1282 # no further data will arrive
792 # so no progress can be made 1283 # so no progress can be made
793 $self->_error (&Errno::EPIPE, 1), return 1284 $self->_error (Errno::EPIPE, 1), return
794 if $self->{_eof}; 1285 if $self->{_eof};
795 1286
796 last; # more data might arrive 1287 last; # more data might arrive
797 } 1288 }
798 } else { 1289 } else {
799 # read side becomes idle 1290 # read side becomes idle
800 delete $self->{_rw}; 1291 delete $self->{_rw} unless $self->{tls};
801 last; 1292 last;
802 } 1293 }
803 } 1294 }
804 1295
805 if ($self->{_eof}) { 1296 if ($self->{_eof}) {
806 if ($self->{on_eof}) { 1297 $self->{on_eof}
807 $self->{on_eof}($self) 1298 ? $self->{on_eof}($self)
808 } else { 1299 : $self->_error (0, 1, "Unexpected end-of-file");
809 $self->_error (0, 1); 1300
810 } 1301 return;
1302 }
1303
1304 if (
1305 defined $self->{rbuf_max}
1306 && $self->{rbuf_max} < length $self->{rbuf}
1307 ) {
1308 $self->_error (Errno::ENOSPC, 1), return;
811 } 1309 }
812 1310
813 # may need to restart read watcher 1311 # may need to restart read watcher
814 unless ($self->{_rw}) { 1312 unless ($self->{_rw}) {
815 $self->start_read 1313 $self->start_read
821 1319
822This replaces the currently set C<on_read> callback, or clears it (when 1320This replaces the currently set C<on_read> callback, or clears it (when
823the new callback is C<undef>). See the description of C<on_read> in the 1321the new callback is C<undef>). See the description of C<on_read> in the
824constructor. 1322constructor.
825 1323
1324This method may invoke callbacks (and therefore the handle might be
1325destroyed after it returns).
1326
826=cut 1327=cut
827 1328
828sub on_read { 1329sub on_read {
829 my ($self, $cb) = @_; 1330 my ($self, $cb) = @_;
830 1331
831 $self->{on_read} = $cb; 1332 $self->{on_read} = $cb;
832 $self->_drain_rbuf if $cb && !$self->{_in_drain}; 1333 $self->_drain_rbuf if $cb;
833} 1334}
834 1335
835=item $handle->rbuf 1336=item $handle->rbuf
836 1337
837Returns the read buffer (as a modifiable lvalue). 1338Returns the read buffer (as a modifiable lvalue). You can also access the
1339read buffer directly as the C<< ->{rbuf} >> member, if you want (this is
1340much faster, and no less clean).
838 1341
839You can access the read buffer directly as the C<< ->{rbuf} >> member, if 1342The only operation allowed on the read buffer (apart from looking at it)
840you want. 1343is removing data from its beginning. Otherwise modifying or appending to
1344it is not allowed and will lead to hard-to-track-down bugs.
841 1345
842NOTE: The read buffer should only be used or modified if the C<on_read>, 1346NOTE: The read buffer should only be used or modified in the C<on_read>
843C<push_read> or C<unshift_read> methods are used. The other read methods 1347callback or when C<push_read> or C<unshift_read> are used with a single
844automatically manage the read buffer. 1348callback (i.e. untyped). Typed C<push_read> and C<unshift_read> methods
1349will manage the read buffer on their own.
845 1350
846=cut 1351=cut
847 1352
848sub rbuf : lvalue { 1353sub rbuf : lvalue {
849 $_[0]{rbuf} 1354 $_[0]{rbuf}
866 1371
867If enough data was available, then the callback must remove all data it is 1372If enough data was available, then the callback must remove all data it is
868interested in (which can be none at all) and return a true value. After returning 1373interested in (which can be none at all) and return a true value. After returning
869true, it will be removed from the queue. 1374true, it will be removed from the queue.
870 1375
1376These methods may invoke callbacks (and therefore the handle might be
1377destroyed after it returns).
1378
871=cut 1379=cut
872 1380
873our %RH; 1381our %RH;
874 1382
875sub register_read_type($$) { 1383sub register_read_type($$) {
881 my $cb = pop; 1389 my $cb = pop;
882 1390
883 if (@_) { 1391 if (@_) {
884 my $type = shift; 1392 my $type = shift;
885 1393
1394 $cb = ($RH{$type} ||= _load_func "$type\::anyevent_read_type"
886 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_read") 1395 or Carp::croak "unsupported/unloadable type '$type' passed to AnyEvent::Handle::push_read")
887 ->($self, $cb, @_); 1396 ->($self, $cb, @_);
888 } 1397 }
889 1398
890 push @{ $self->{_queue} }, $cb; 1399 push @{ $self->{_queue} }, $cb;
891 $self->_drain_rbuf unless $self->{_in_drain}; 1400 $self->_drain_rbuf;
892} 1401}
893 1402
894sub unshift_read { 1403sub unshift_read {
895 my $self = shift; 1404 my $self = shift;
896 my $cb = pop; 1405 my $cb = pop;
897 1406
898 if (@_) { 1407 if (@_) {
899 my $type = shift; 1408 my $type = shift;
900 1409
1410 $cb = ($RH{$type} ||= _load_func "$type\::anyevent_read_type"
901 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::unshift_read") 1411 or Carp::croak "unsupported/unloadable type '$type' passed to AnyEvent::Handle::unshift_read")
902 ->($self, $cb, @_); 1412 ->($self, $cb, @_);
903 } 1413 }
904 1414
905
906 unshift @{ $self->{_queue} }, $cb; 1415 unshift @{ $self->{_queue} }, $cb;
907 $self->_drain_rbuf unless $self->{_in_drain}; 1416 $self->_drain_rbuf;
908} 1417}
909 1418
910=item $handle->push_read (type => @args, $cb) 1419=item $handle->push_read (type => @args, $cb)
911 1420
912=item $handle->unshift_read (type => @args, $cb) 1421=item $handle->unshift_read (type => @args, $cb)
913 1422
914Instead of providing a callback that parses the data itself you can chose 1423Instead of providing a callback that parses the data itself you can chose
915between a number of predefined parsing formats, for chunks of data, lines 1424between a number of predefined parsing formats, for chunks of data, lines
916etc. 1425etc. You can also specify the (fully qualified) name of a package, in
1426which case AnyEvent tries to load the package and then expects to find the
1427C<anyevent_read_type> function inside (see "custom read types", below).
917 1428
918Predefined types are (if you have ideas for additional types, feel free to 1429Predefined types are (if you have ideas for additional types, feel free to
919drop by and tell us): 1430drop by and tell us):
920 1431
921=over 4 1432=over 4
927data. 1438data.
928 1439
929Example: read 2 bytes. 1440Example: read 2 bytes.
930 1441
931 $handle->push_read (chunk => 2, sub { 1442 $handle->push_read (chunk => 2, sub {
932 warn "yay ", unpack "H*", $_[1]; 1443 say "yay " . unpack "H*", $_[1];
933 }); 1444 });
934 1445
935=cut 1446=cut
936 1447
937register_read_type chunk => sub { 1448register_read_type chunk => sub {
971 if (@_ < 3) { 1482 if (@_ < 3) {
972 # this is more than twice as fast as the generic code below 1483 # this is more than twice as fast as the generic code below
973 sub { 1484 sub {
974 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return; 1485 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return;
975 1486
976 $cb->($_[0], $1, $2); 1487 $cb->($_[0], "$1", "$2");
977 1 1488 1
978 } 1489 }
979 } else { 1490 } else {
980 $eol = quotemeta $eol unless ref $eol; 1491 $eol = quotemeta $eol unless ref $eol;
981 $eol = qr|^(.*?)($eol)|s; 1492 $eol = qr|^(.*?)($eol)|s;
982 1493
983 sub { 1494 sub {
984 $_[0]{rbuf} =~ s/$eol// or return; 1495 $_[0]{rbuf} =~ s/$eol// or return;
985 1496
986 $cb->($_[0], $1, $2); 1497 $cb->($_[0], "$1", "$2");
987 1 1498 1
988 } 1499 }
989 } 1500 }
990}; 1501};
991 1502
1013the receive buffer when neither C<$accept> nor C<$reject> match, 1524the receive buffer when neither C<$accept> nor C<$reject> match,
1014and everything preceding and including the match will be accepted 1525and everything preceding and including the match will be accepted
1015unconditionally. This is useful to skip large amounts of data that you 1526unconditionally. This is useful to skip large amounts of data that you
1016know cannot be matched, so that the C<$accept> or C<$reject> regex do not 1527know cannot be matched, so that the C<$accept> or C<$reject> regex do not
1017have to start matching from the beginning. This is purely an optimisation 1528have to start matching from the beginning. This is purely an optimisation
1018and is usually worth only when you expect more than a few kilobytes. 1529and is usually worth it only when you expect more than a few kilobytes.
1019 1530
1020Example: expect a http header, which ends at C<\015\012\015\012>. Since we 1531Example: expect a http header, which ends at C<\015\012\015\012>. Since we
1021expect the header to be very large (it isn't in practise, but...), we use 1532expect the header to be very large (it isn't in practice, but...), we use
1022a skip regex to skip initial portions. The skip regex is tricky in that 1533a skip regex to skip initial portions. The skip regex is tricky in that
1023it only accepts something not ending in either \015 or \012, as these are 1534it only accepts something not ending in either \015 or \012, as these are
1024required for the accept regex. 1535required for the accept regex.
1025 1536
1026 $handle->push_read (regex => 1537 $handle->push_read (regex =>
1039 1550
1040 sub { 1551 sub {
1041 # accept 1552 # accept
1042 if ($$rbuf =~ $accept) { 1553 if ($$rbuf =~ $accept) {
1043 $data .= substr $$rbuf, 0, $+[0], ""; 1554 $data .= substr $$rbuf, 0, $+[0], "";
1044 $cb->($self, $data); 1555 $cb->($_[0], $data);
1045 return 1; 1556 return 1;
1046 } 1557 }
1047 1558
1048 # reject 1559 # reject
1049 if ($reject && $$rbuf =~ $reject) { 1560 if ($reject && $$rbuf =~ $reject) {
1050 $self->_error (&Errno::EBADMSG); 1561 $_[0]->_error (Errno::EBADMSG);
1051 } 1562 }
1052 1563
1053 # skip 1564 # skip
1054 if ($skip && $$rbuf =~ $skip) { 1565 if ($skip && $$rbuf =~ $skip) {
1055 $data .= substr $$rbuf, 0, $+[0], ""; 1566 $data .= substr $$rbuf, 0, $+[0], "";
1071 my ($self, $cb) = @_; 1582 my ($self, $cb) = @_;
1072 1583
1073 sub { 1584 sub {
1074 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) { 1585 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) {
1075 if ($_[0]{rbuf} =~ /[^0-9]/) { 1586 if ($_[0]{rbuf} =~ /[^0-9]/) {
1076 $self->_error (&Errno::EBADMSG); 1587 $_[0]->_error (Errno::EBADMSG);
1077 } 1588 }
1078 return; 1589 return;
1079 } 1590 }
1080 1591
1081 my $len = $1; 1592 my $len = $1;
1082 1593
1083 $self->unshift_read (chunk => $len, sub { 1594 $_[0]->unshift_read (chunk => $len, sub {
1084 my $string = $_[1]; 1595 my $string = $_[1];
1085 $_[0]->unshift_read (chunk => 1, sub { 1596 $_[0]->unshift_read (chunk => 1, sub {
1086 if ($_[1] eq ",") { 1597 if ($_[1] eq ",") {
1087 $cb->($_[0], $string); 1598 $cb->($_[0], $string);
1088 } else { 1599 } else {
1089 $self->_error (&Errno::EBADMSG); 1600 $_[0]->_error (Errno::EBADMSG);
1090 } 1601 }
1091 }); 1602 });
1092 }); 1603 });
1093 1604
1094 1 1605 1
1100An octet string prefixed with an encoded length. The encoding C<$format> 1611An octet string prefixed with an encoded length. The encoding C<$format>
1101uses the same format as a Perl C<pack> format, but must specify a single 1612uses the same format as a Perl C<pack> format, but must specify a single
1102integer only (only one of C<cCsSlLqQiInNvVjJw> is allowed, plus an 1613integer only (only one of C<cCsSlLqQiInNvVjJw> is allowed, plus an
1103optional C<!>, C<< < >> or C<< > >> modifier). 1614optional C<!>, C<< < >> or C<< > >> modifier).
1104 1615
1105DNS over TCP uses a prefix of C<n>, EPP uses a prefix of C<N>. 1616For example, DNS over TCP uses a prefix of C<n> (2 octet network order),
1617EPP uses a prefix of C<N> (4 octtes).
1106 1618
1107Example: read a block of data prefixed by its length in BER-encoded 1619Example: read a block of data prefixed by its length in BER-encoded
1108format (very efficient). 1620format (very efficient).
1109 1621
1110 $handle->push_read (packstring => "w", sub { 1622 $handle->push_read (packstring => "w", sub {
1140 } 1652 }
1141}; 1653};
1142 1654
1143=item json => $cb->($handle, $hash_or_arrayref) 1655=item json => $cb->($handle, $hash_or_arrayref)
1144 1656
1145Reads a JSON object or array, decodes it and passes it to the callback. 1657Reads a JSON object or array, decodes it and passes it to the
1658callback. When a parse error occurs, an C<EBADMSG> error will be raised.
1146 1659
1147If a C<json> object was passed to the constructor, then that will be used 1660If a C<json> object was passed to the constructor, then that will be used
1148for the final decode, otherwise it will create a JSON coder expecting UTF-8. 1661for the final decode, otherwise it will create a JSON coder expecting UTF-8.
1149 1662
1150This read type uses the incremental parser available with JSON version 1663This read type uses the incremental parser available with JSON version
1159=cut 1672=cut
1160 1673
1161register_read_type json => sub { 1674register_read_type json => sub {
1162 my ($self, $cb) = @_; 1675 my ($self, $cb) = @_;
1163 1676
1164 require JSON; 1677 my $json = $self->{json} ||= json_coder;
1165 1678
1166 my $data; 1679 my $data;
1167 my $rbuf = \$self->{rbuf}; 1680 my $rbuf = \$self->{rbuf};
1168 1681
1169 my $json = $self->{json} ||= JSON->new->utf8;
1170
1171 sub { 1682 sub {
1172 my $ref = $json->incr_parse ($self->{rbuf}); 1683 my $ref = eval { $json->incr_parse ($_[0]{rbuf}) };
1173 1684
1174 if ($ref) { 1685 if ($ref) {
1175 $self->{rbuf} = $json->incr_text; 1686 $_[0]{rbuf} = $json->incr_text;
1176 $json->incr_text = ""; 1687 $json->incr_text = "";
1177 $cb->($self, $ref); 1688 $cb->($_[0], $ref);
1178 1689
1179 1 1690 1
1691 } elsif ($@) {
1692 # error case
1693 $json->incr_skip;
1694
1695 $_[0]{rbuf} = $json->incr_text;
1696 $json->incr_text = "";
1697
1698 $_[0]->_error (Errno::EBADMSG);
1699
1700 ()
1180 } else { 1701 } else {
1181 $self->{rbuf} = ""; 1702 $_[0]{rbuf} = "";
1703
1182 () 1704 ()
1183 } 1705 }
1184 } 1706 }
1185}; 1707};
1186 1708
1195=cut 1717=cut
1196 1718
1197register_read_type storable => sub { 1719register_read_type storable => sub {
1198 my ($self, $cb) = @_; 1720 my ($self, $cb) = @_;
1199 1721
1200 require Storable; 1722 require Storable unless $Storable::VERSION;
1201 1723
1202 sub { 1724 sub {
1203 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method 1725 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method
1204 defined (my $len = eval { unpack "w", $_[0]{rbuf} }) 1726 defined (my $len = eval { unpack "w", $_[0]{rbuf} })
1205 or return; 1727 or return;
1218 # read remaining chunk 1740 # read remaining chunk
1219 $_[0]->unshift_read (chunk => $len, sub { 1741 $_[0]->unshift_read (chunk => $len, sub {
1220 if (my $ref = eval { Storable::thaw ($_[1]) }) { 1742 if (my $ref = eval { Storable::thaw ($_[1]) }) {
1221 $cb->($_[0], $ref); 1743 $cb->($_[0], $ref);
1222 } else { 1744 } else {
1223 $self->_error (&Errno::EBADMSG); 1745 $_[0]->_error (Errno::EBADMSG);
1224 } 1746 }
1225 }); 1747 });
1226 } 1748 }
1227 1749
1228 1 1750 1
1229 } 1751 }
1230}; 1752};
1231 1753
1232=back 1754=back
1233 1755
1234=item AnyEvent::Handle::register_read_type type => $coderef->($handle, $cb, @args) 1756=item custom read types - Package::anyevent_read_type $handle, $cb, @args
1235 1757
1236This function (not method) lets you add your own types to C<push_read>. 1758Instead of one of the predefined types, you can also specify the name
1759of a package. AnyEvent will try to load the package and then expects to
1760find a function named C<anyevent_read_type> inside. If it isn't found, it
1761progressively tries to load the parent package until it either finds the
1762function (good) or runs out of packages (bad).
1237 1763
1238Whenever the given C<type> is used, C<push_read> will invoke the code 1764Whenever this type is used, C<push_read> will invoke the function with the
1239reference with the handle object, the callback and the remaining 1765handle object, the original callback and the remaining arguments.
1240arguments.
1241 1766
1242The code reference is supposed to return a callback (usually a closure) 1767The function is supposed to return a callback (usually a closure) that
1243that works as a plain read callback (see C<< ->push_read ($cb) >>). 1768works as a plain read callback (see C<< ->push_read ($cb) >>), so you can
1769mentally treat the function as a "configurable read type to read callback"
1770converter.
1244 1771
1245It should invoke the passed callback when it is done reading (remember to 1772It should invoke the original callback when it is done reading (remember
1246pass C<$handle> as first argument as all other callbacks do that). 1773to pass C<$handle> as first argument as all other callbacks do that,
1774although there is no strict requirement on this).
1247 1775
1248Note that this is a function, and all types registered this way will be
1249global, so try to use unique names.
1250
1251For examples, see the source of this module (F<perldoc -m AnyEvent::Handle>, 1776For examples, see the source of this module (F<perldoc -m
1252search for C<register_read_type>)). 1777AnyEvent::Handle>, search for C<register_read_type>)).
1253 1778
1254=item $handle->stop_read 1779=item $handle->stop_read
1255 1780
1256=item $handle->start_read 1781=item $handle->start_read
1257 1782
1263Note that AnyEvent::Handle will automatically C<start_read> for you when 1788Note that AnyEvent::Handle will automatically C<start_read> for you when
1264you change the C<on_read> callback or push/unshift a read callback, and it 1789you change the C<on_read> callback or push/unshift a read callback, and it
1265will automatically C<stop_read> for you when neither C<on_read> is set nor 1790will automatically C<stop_read> for you when neither C<on_read> is set nor
1266there are any read requests in the queue. 1791there are any read requests in the queue.
1267 1792
1793In older versions of this module (<= 5.3), these methods had no effect,
1794as TLS does not support half-duplex connections. In current versions they
1795work as expected, as this behaviour is required to avoid certain resource
1796attacks, where the program would be forced to read (and buffer) arbitrary
1797amounts of data before being able to send some data. The drawback is that
1798some readings of the the SSL/TLS specifications basically require this
1799attack to be working, as SSL/TLS implementations might stall sending data
1800during a rehandshake.
1801
1802As a guideline, during the initial handshake, you should not stop reading,
1803and as a client, it might cause problems, depending on your application.
1804
1268=cut 1805=cut
1269 1806
1270sub stop_read { 1807sub stop_read {
1271 my ($self) = @_; 1808 my ($self) = @_;
1272 1809
1274} 1811}
1275 1812
1276sub start_read { 1813sub start_read {
1277 my ($self) = @_; 1814 my ($self) = @_;
1278 1815
1279 unless ($self->{_rw} || $self->{_eof}) { 1816 unless ($self->{_rw} || $self->{_eof} || !$self->{fh}) {
1280 Scalar::Util::weaken $self; 1817 Scalar::Util::weaken $self;
1281 1818
1282 $self->{_rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub { 1819 $self->{_rw} = AE::io $self->{fh}, 0, sub {
1283 my $rbuf = $self->{filter_r} ? \my $buf : \$self->{rbuf}; 1820 my $rbuf = \($self->{tls} ? my $buf : $self->{rbuf});
1284 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf; 1821 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size}, length $$rbuf;
1285 1822
1286 if ($len > 0) { 1823 if ($len > 0) {
1287 $self->{_activity} = AnyEvent->now; 1824 $self->{_activity} = $self->{_ractivity} = AE::now;
1288 1825
1289 $self->{filter_r} 1826 if ($self->{tls}) {
1290 ? $self->{filter_r}($self, $rbuf) 1827 Net::SSLeay::BIO_write ($self->{_rbio}, $$rbuf);
1291 : $self->{_in_drain} || $self->_drain_rbuf; 1828
1829 &_dotls ($self);
1830 } else {
1831 $self->_drain_rbuf;
1832 }
1833
1834 if ($len == $self->{read_size}) {
1835 $self->{read_size} *= 2;
1836 $self->{read_size} = $self->{max_read_size} || MAX_READ_SIZE
1837 if $self->{read_size} > ($self->{max_read_size} || MAX_READ_SIZE);
1838 }
1292 1839
1293 } elsif (defined $len) { 1840 } elsif (defined $len) {
1294 delete $self->{_rw}; 1841 delete $self->{_rw};
1295 $self->{_eof} = 1; 1842 $self->{_eof} = 1;
1296 $self->_drain_rbuf unless $self->{_in_drain}; 1843 $self->_drain_rbuf;
1297 1844
1298 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) { 1845 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {
1299 return $self->_error ($!, 1); 1846 return $self->_error ($!, 1);
1300 } 1847 }
1301 }); 1848 };
1302 } 1849 }
1303} 1850}
1304 1851
1852our $ERROR_SYSCALL;
1853our $ERROR_WANT_READ;
1854
1855sub _tls_error {
1856 my ($self, $err) = @_;
1857
1858 return $self->_error ($!, 1)
1859 if $err == Net::SSLeay::ERROR_SYSCALL ();
1860
1861 my $err =Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ());
1862
1863 # reduce error string to look less scary
1864 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /;
1865
1866 if ($self->{_on_starttls}) {
1867 (delete $self->{_on_starttls})->($self, undef, $err);
1868 &_freetls;
1869 } else {
1870 &_freetls;
1871 $self->_error (Errno::EPROTO, 1, $err);
1872 }
1873}
1874
1875# poll the write BIO and send the data if applicable
1876# also decode read data if possible
1877# this is basiclaly our TLS state machine
1878# more efficient implementations are possible with openssl,
1879# but not with the buggy and incomplete Net::SSLeay.
1305sub _dotls { 1880sub _dotls {
1306 my ($self) = @_; 1881 my ($self) = @_;
1307 1882
1308 my $buf; 1883 my $tmp;
1309 1884
1310 if (length $self->{_tls_wbuf}) { 1885 if (length $self->{_tls_wbuf}) {
1311 while ((my $len = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) { 1886 while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) {
1312 substr $self->{_tls_wbuf}, 0, $len, ""; 1887 substr $self->{_tls_wbuf}, 0, $tmp, "";
1313 } 1888 }
1314 }
1315 1889
1890 $tmp = Net::SSLeay::get_error ($self->{tls}, $tmp);
1891 return $self->_tls_error ($tmp)
1892 if $tmp != $ERROR_WANT_READ
1893 && ($tmp != $ERROR_SYSCALL || $!);
1894 }
1895
1896 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
1897 unless (length $tmp) {
1898 $self->{_on_starttls}
1899 and (delete $self->{_on_starttls})->($self, undef, "EOF during handshake"); # ???
1900 &_freetls;
1901
1902 if ($self->{on_stoptls}) {
1903 $self->{on_stoptls}($self);
1904 return;
1905 } else {
1906 # let's treat SSL-eof as we treat normal EOF
1907 delete $self->{_rw};
1908 $self->{_eof} = 1;
1909 }
1910 }
1911
1912 $self->{_tls_rbuf} .= $tmp;
1913 $self->_drain_rbuf;
1914 $self->{tls} or return; # tls session might have gone away in callback
1915 }
1916
1917 $tmp = Net::SSLeay::get_error ($self->{tls}, -1);
1918 return $self->_tls_error ($tmp)
1919 if $tmp != $ERROR_WANT_READ
1920 && ($tmp != $ERROR_SYSCALL || $!);
1921
1316 if (length ($buf = Net::SSLeay::BIO_read ($self->{_wbio}))) { 1922 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {
1317 $self->{wbuf} .= $buf; 1923 $self->{wbuf} .= $tmp;
1318 $self->_drain_wbuf; 1924 $self->_drain_wbuf;
1925 $self->{tls} or return; # tls session might have gone away in callback
1319 } 1926 }
1320 1927
1321 while (defined ($buf = Net::SSLeay::read ($self->{tls}))) { 1928 $self->{_on_starttls}
1322 if (length $buf) { 1929 and Net::SSLeay::state ($self->{tls}) == Net::SSLeay::ST_OK ()
1323 $self->{rbuf} .= $buf; 1930 and (delete $self->{_on_starttls})->($self, 1, "TLS/SSL connection established");
1324 $self->_drain_rbuf unless $self->{_in_drain};
1325 } else {
1326 # let's treat SSL-eof as we treat normal EOF
1327 $self->{_eof} = 1;
1328 $self->_shutdown;
1329 return;
1330 }
1331 }
1332
1333 my $err = Net::SSLeay::get_error ($self->{tls}, -1);
1334
1335 if ($err!= Net::SSLeay::ERROR_WANT_READ ()) {
1336 if ($err == Net::SSLeay::ERROR_SYSCALL ()) {
1337 return $self->_error ($!, 1);
1338 } elsif ($err == Net::SSLeay::ERROR_SSL ()) {
1339 return $self->_error (&Errno::EIO, 1);
1340 }
1341
1342 # all others are fine for our purposes
1343 }
1344} 1931}
1345 1932
1346=item $handle->starttls ($tls[, $tls_ctx]) 1933=item $handle->starttls ($tls[, $tls_ctx])
1347 1934
1348Instead of starting TLS negotiation immediately when the AnyEvent::Handle 1935Instead of starting TLS negotiation immediately when the AnyEvent::Handle
1349object is created, you can also do that at a later time by calling 1936object is created, you can also do that at a later time by calling
1350C<starttls>. 1937C<starttls>.
1351 1938
1939Starting TLS is currently an asynchronous operation - when you push some
1940write data and then call C<< ->starttls >> then TLS negotiation will start
1941immediately, after which the queued write data is then sent.
1942
1352The first argument is the same as the C<tls> constructor argument (either 1943The first argument is the same as the C<tls> constructor argument (either
1353C<"connect">, C<"accept"> or an existing Net::SSLeay object). 1944C<"connect">, C<"accept"> or an existing Net::SSLeay object).
1354 1945
1355The second argument is the optional C<Net::SSLeay::CTX> object that is 1946The second argument is the optional C<AnyEvent::TLS> object that is used
1356used when AnyEvent::Handle has to create its own TLS connection object. 1947when AnyEvent::Handle has to create its own TLS connection object, or
1948a hash reference with C<< key => value >> pairs that will be used to
1949construct a new context.
1357 1950
1358The TLS connection object will end up in C<< $handle->{tls} >> after this 1951The TLS connection object will end up in C<< $handle->{tls} >>, the TLS
1359call and can be used or changed to your liking. Note that the handshake 1952context in C<< $handle->{tls_ctx} >> after this call and can be used or
1360might have already started when this function returns. 1953changed to your liking. Note that the handshake might have already started
1954when this function returns.
1361 1955
1956Due to bugs in OpenSSL, it might or might not be possible to do multiple
1957handshakes on the same stream. It is best to not attempt to use the
1958stream after stopping TLS.
1959
1960This method may invoke callbacks (and therefore the handle might be
1961destroyed after it returns).
1962
1362=cut 1963=cut
1964
1965our %TLS_CACHE; #TODO not yet documented, should we?
1363 1966
1364sub starttls { 1967sub starttls {
1365 my ($self, $ssl, $ctx) = @_; 1968 my ($self, $tls, $ctx) = @_;
1366 1969
1367 $self->stoptls; 1970 Carp::croak "It is an error to call starttls on an AnyEvent::Handle object while TLS is already active, caught"
1971 if $self->{tls};
1368 1972
1369 if ($ssl eq "accept") { 1973 $self->{tls} = $tls;
1370 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ()); 1974 $self->{tls_ctx} = $ctx if @_ > 2;
1371 Net::SSLeay::set_accept_state ($ssl); 1975
1372 } elsif ($ssl eq "connect") { 1976 return unless $self->{fh};
1373 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ()); 1977
1374 Net::SSLeay::set_connect_state ($ssl); 1978 require Net::SSLeay;
1979
1980 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL ();
1981 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ ();
1982
1983 $tls = delete $self->{tls};
1984 $ctx = $self->{tls_ctx};
1985
1986 local $Carp::CarpLevel = 1; # skip ourselves when creating a new context or session
1987
1988 if ("HASH" eq ref $ctx) {
1989 require AnyEvent::TLS;
1990
1991 if ($ctx->{cache}) {
1992 my $key = $ctx+0;
1993 $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx;
1994 } else {
1995 $ctx = new AnyEvent::TLS %$ctx;
1996 }
1997 }
1375 } 1998
1376 1999 $self->{tls_ctx} = $ctx || TLS_CTX ();
1377 $self->{tls} = $ssl; 2000 $self->{tls} = $tls = $self->{tls_ctx}->_get_session ($tls, $self, $self->{peername});
1378 2001
1379 # basically, this is deep magic (because SSL_read should have the same issues) 2002 # basically, this is deep magic (because SSL_read should have the same issues)
1380 # but the openssl maintainers basically said: "trust us, it just works". 2003 # but the openssl maintainers basically said: "trust us, it just works".
1381 # (unfortunately, we have to hardcode constants because the abysmally misdesigned 2004 # (unfortunately, we have to hardcode constants because the abysmally misdesigned
1382 # and mismaintained ssleay-module doesn't even offer them). 2005 # and mismaintained ssleay-module doesn't even offer them).
1383 # http://www.mail-archive.com/openssl-dev@openssl.org/msg22420.html 2006 # http://www.mail-archive.com/openssl-dev@openssl.org/msg22420.html
1384 # 2007 #
1385 # in short: this is a mess. 2008 # in short: this is a mess.
1386 # 2009 #
1387 # note that we do not try to kepe the length constant between writes as we are required to do. 2010 # note that we do not try to keep the length constant between writes as we are required to do.
1388 # we assume that most (but not all) of this insanity only applies to non-blocking cases, 2011 # we assume that most (but not all) of this insanity only applies to non-blocking cases,
1389 # and we drive openssl fully in blocking mode here. 2012 # and we drive openssl fully in blocking mode here. Or maybe we don't - openssl seems to
2013 # have identity issues in that area.
1390 Net::SSLeay::CTX_set_mode ($self->{tls}, 2014# Net::SSLeay::CTX_set_mode ($ssl,
1391 (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1) 2015# (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1)
1392 | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2)); 2016# | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2));
2017 Net::SSLeay::CTX_set_mode ($tls, 1|2);
1393 2018
1394 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 2019 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1395 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 2020 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1396 2021
2022 Net::SSLeay::BIO_write ($self->{_rbio}, $self->{rbuf});
2023 $self->{rbuf} = "";
2024
1397 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio}); 2025 Net::SSLeay::set_bio ($tls, $self->{_rbio}, $self->{_wbio});
1398 2026
1399 $self->{filter_w} = sub { 2027 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) }
1400 $_[0]{_tls_wbuf} .= ${$_[1]}; 2028 if $self->{on_starttls};
1401 &_dotls; 2029
1402 }; 2030 &_dotls; # need to trigger the initial handshake
1403 $self->{filter_r} = sub { 2031 $self->start_read; # make sure we actually do read
1404 Net::SSLeay::BIO_write ($_[0]{_rbio}, ${$_[1]});
1405 &_dotls;
1406 };
1407} 2032}
1408 2033
1409=item $handle->stoptls 2034=item $handle->stoptls
1410 2035
1411Destroys the SSL connection, if any. Partial read or write data will be 2036Shuts down the SSL connection - this makes a proper EOF handshake by
1412lost. 2037sending a close notify to the other side, but since OpenSSL doesn't
2038support non-blocking shut downs, it is not guaranteed that you can re-use
2039the stream afterwards.
2040
2041This method may invoke callbacks (and therefore the handle might be
2042destroyed after it returns).
1413 2043
1414=cut 2044=cut
1415 2045
1416sub stoptls { 2046sub stoptls {
1417 my ($self) = @_; 2047 my ($self) = @_;
1418 2048
1419 Net::SSLeay::free (delete $self->{tls}) if $self->{tls}; 2049 if ($self->{tls} && $self->{fh}) {
2050 Net::SSLeay::shutdown ($self->{tls});
1420 2051
1421 delete $self->{_rbio}; 2052 &_dotls;
1422 delete $self->{_wbio}; 2053
1423 delete $self->{_tls_wbuf}; 2054# # we don't give a shit. no, we do, but we can't. no...#d#
1424 delete $self->{filter_r}; 2055# # we, we... have to use openssl :/#d#
1425 delete $self->{filter_w}; 2056# &_freetls;#d#
2057 }
1426} 2058}
2059
2060sub _freetls {
2061 my ($self) = @_;
2062
2063 return unless $self->{tls};
2064
2065 $self->{tls_ctx}->_put_session (delete $self->{tls})
2066 if $self->{tls} > 0;
2067
2068 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)};
2069}
2070
2071=item $handle->resettls
2072
2073This rarely-used method simply resets and TLS state on the handle, usually
2074causing data loss.
2075
2076One case where it may be useful is when you want to skip over the data in
2077the stream but you are not interested in interpreting it, so data loss is
2078no concern.
2079
2080=cut
2081
2082*resettls = \&_freetls;
1427 2083
1428sub DESTROY { 2084sub DESTROY {
1429 my $self = shift; 2085 my ($self) = @_;
1430 2086
1431 $self->stoptls; 2087 &_freetls;
1432 2088
1433 my $linger = exists $self->{linger} ? $self->{linger} : 3600; 2089 my $linger = exists $self->{linger} ? $self->{linger} : 3600;
1434 2090
1435 if ($linger && length $self->{wbuf}) { 2091 if ($linger && length $self->{wbuf} && $self->{fh}) {
1436 my $fh = delete $self->{fh}; 2092 my $fh = delete $self->{fh};
1437 my $wbuf = delete $self->{wbuf}; 2093 my $wbuf = delete $self->{wbuf};
1438 2094
1439 my @linger; 2095 my @linger;
1440 2096
1441 push @linger, AnyEvent->io (fh => $fh, poll => "w", cb => sub { 2097 push @linger, AE::io $fh, 1, sub {
1442 my $len = syswrite $fh, $wbuf, length $wbuf; 2098 my $len = syswrite $fh, $wbuf, length $wbuf;
1443 2099
1444 if ($len > 0) { 2100 if ($len > 0) {
1445 substr $wbuf, 0, $len, ""; 2101 substr $wbuf, 0, $len, "";
1446 } else { 2102 } elsif (defined $len || ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK)) {
1447 @linger = (); # end 2103 @linger = (); # end
1448 } 2104 }
2105 };
2106 push @linger, AE::timer $linger, 0, sub {
2107 @linger = ();
2108 };
2109 }
2110}
2111
2112=item $handle->destroy
2113
2114Shuts down the handle object as much as possible - this call ensures that
2115no further callbacks will be invoked and as many resources as possible
2116will be freed. Any method you will call on the handle object after
2117destroying it in this way will be silently ignored (and it will return the
2118empty list).
2119
2120Normally, you can just "forget" any references to an AnyEvent::Handle
2121object and it will simply shut down. This works in fatal error and EOF
2122callbacks, as well as code outside. It does I<NOT> work in a read or write
2123callback, so when you want to destroy the AnyEvent::Handle object from
2124within such an callback. You I<MUST> call C<< ->destroy >> explicitly in
2125that case.
2126
2127Destroying the handle object in this way has the advantage that callbacks
2128will be removed as well, so if those are the only reference holders (as
2129is common), then one doesn't need to do anything special to break any
2130reference cycles.
2131
2132The handle might still linger in the background and write out remaining
2133data, as specified by the C<linger> option, however.
2134
2135=cut
2136
2137sub destroy {
2138 my ($self) = @_;
2139
2140 $self->DESTROY;
2141 %$self = ();
2142 bless $self, "AnyEvent::Handle::destroyed";
2143}
2144
2145sub AnyEvent::Handle::destroyed::AUTOLOAD {
2146 #nop
2147}
2148
2149=item $handle->destroyed
2150
2151Returns false as long as the handle hasn't been destroyed by a call to C<<
2152->destroy >>, true otherwise.
2153
2154Can be useful to decide whether the handle is still valid after some
2155callback possibly destroyed the handle. For example, C<< ->push_write >>,
2156C<< ->starttls >> and other methods can call user callbacks, which in turn
2157can destroy the handle, so work can be avoided by checking sometimes:
2158
2159 $hdl->starttls ("accept");
2160 return if $hdl->destroyed;
2161 $hdl->push_write (...
2162
2163Note that the call to C<push_write> will silently be ignored if the handle
2164has been destroyed, so often you can just ignore the possibility of the
2165handle being destroyed.
2166
2167=cut
2168
2169sub destroyed { 0 }
2170sub AnyEvent::Handle::destroyed::destroyed { 1 }
2171
2172=item AnyEvent::Handle::TLS_CTX
2173
2174This function creates and returns the AnyEvent::TLS object used by default
2175for TLS mode.
2176
2177The context is created by calling L<AnyEvent::TLS> without any arguments.
2178
2179=cut
2180
2181our $TLS_CTX;
2182
2183sub TLS_CTX() {
2184 $TLS_CTX ||= do {
2185 require AnyEvent::TLS;
2186
2187 new AnyEvent::TLS
2188 }
2189}
2190
2191=back
2192
2193
2194=head1 NONFREQUENTLY ASKED QUESTIONS
2195
2196=over 4
2197
2198=item I C<undef> the AnyEvent::Handle reference inside my callback and
2199still get further invocations!
2200
2201That's because AnyEvent::Handle keeps a reference to itself when handling
2202read or write callbacks.
2203
2204It is only safe to "forget" the reference inside EOF or error callbacks,
2205from within all other callbacks, you need to explicitly call the C<<
2206->destroy >> method.
2207
2208=item Why is my C<on_eof> callback never called?
2209
2210Probably because your C<on_error> callback is being called instead: When
2211you have outstanding requests in your read queue, then an EOF is
2212considered an error as you clearly expected some data.
2213
2214To avoid this, make sure you have an empty read queue whenever your handle
2215is supposed to be "idle" (i.e. connection closes are O.K.). You can set
2216an C<on_read> handler that simply pushes the first read requests in the
2217queue.
2218
2219See also the next question, which explains this in a bit more detail.
2220
2221=item How can I serve requests in a loop?
2222
2223Most protocols consist of some setup phase (authentication for example)
2224followed by a request handling phase, where the server waits for requests
2225and handles them, in a loop.
2226
2227There are two important variants: The first (traditional, better) variant
2228handles requests until the server gets some QUIT command, causing it to
2229close the connection first (highly desirable for a busy TCP server). A
2230client dropping the connection is an error, which means this variant can
2231detect an unexpected detection close.
2232
2233To handle this case, always make sure you have a on-empty read queue, by
2234pushing the "read request start" handler on it:
2235
2236 # we assume a request starts with a single line
2237 my @start_request; @start_request = (line => sub {
2238 my ($hdl, $line) = @_;
2239
2240 ... handle request
2241
2242 # push next request read, possibly from a nested callback
2243 $hdl->push_read (@start_request);
2244 });
2245
2246 # auth done, now go into request handling loop
2247 # now push the first @start_request
2248 $hdl->push_read (@start_request);
2249
2250By always having an outstanding C<push_read>, the handle always expects
2251some data and raises the C<EPIPE> error when the connction is dropped
2252unexpectedly.
2253
2254The second variant is a protocol where the client can drop the connection
2255at any time. For TCP, this means that the server machine may run out of
2256sockets easier, and in general, it means you cannot distinguish a protocl
2257failure/client crash from a normal connection close. Nevertheless, these
2258kinds of protocols are common (and sometimes even the best solution to the
2259problem).
2260
2261Having an outstanding read request at all times is possible if you ignore
2262C<EPIPE> errors, but this doesn't help with when the client drops the
2263connection during a request, which would still be an error.
2264
2265A better solution is to push the initial request read in an C<on_read>
2266callback. This avoids an error, as when the server doesn't expect data
2267(i.e. is idly waiting for the next request, an EOF will not raise an
2268error, but simply result in an C<on_eof> callback. It is also a bit slower
2269and simpler:
2270
2271 # auth done, now go into request handling loop
2272 $hdl->on_read (sub {
2273 my ($hdl) = @_;
2274
2275 # called each time we receive data but the read queue is empty
2276 # simply start read the request
2277
2278 $hdl->push_read (line => sub {
2279 my ($hdl, $line) = @_;
2280
2281 ... handle request
2282
2283 # do nothing special when the request has been handled, just
2284 # let the request queue go empty.
1449 }); 2285 });
1450 push @linger, AnyEvent->timer (after => $linger, cb => sub {
1451 @linger = ();
1452 }); 2286 });
2287
2288=item I get different callback invocations in TLS mode/Why can't I pause
2289reading?
2290
2291Unlike, say, TCP, TLS connections do not consist of two independent
2292communication channels, one for each direction. Or put differently, the
2293read and write directions are not independent of each other: you cannot
2294write data unless you are also prepared to read, and vice versa.
2295
2296This means that, in TLS mode, you might get C<on_error> or C<on_eof>
2297callback invocations when you are not expecting any read data - the reason
2298is that AnyEvent::Handle always reads in TLS mode.
2299
2300During the connection, you have to make sure that you always have a
2301non-empty read-queue, or an C<on_read> watcher. At the end of the
2302connection (or when you no longer want to use it) you can call the
2303C<destroy> method.
2304
2305=item How do I read data until the other side closes the connection?
2306
2307If you just want to read your data into a perl scalar, the easiest way
2308to achieve this is by setting an C<on_read> callback that does nothing,
2309clearing the C<on_eof> callback and in the C<on_error> callback, the data
2310will be in C<$_[0]{rbuf}>:
2311
2312 $handle->on_read (sub { });
2313 $handle->on_eof (undef);
2314 $handle->on_error (sub {
2315 my $data = delete $_[0]{rbuf};
2316 });
2317
2318Note that this example removes the C<rbuf> member from the handle object,
2319which is not normally allowed by the API. It is expressly permitted in
2320this case only, as the handle object needs to be destroyed afterwards.
2321
2322The reason to use C<on_error> is that TCP connections, due to latencies
2323and packets loss, might get closed quite violently with an error, when in
2324fact all data has been received.
2325
2326It is usually better to use acknowledgements when transferring data,
2327to make sure the other side hasn't just died and you got the data
2328intact. This is also one reason why so many internet protocols have an
2329explicit QUIT command.
2330
2331=item I don't want to destroy the handle too early - how do I wait until
2332all data has been written?
2333
2334After writing your last bits of data, set the C<on_drain> callback
2335and destroy the handle in there - with the default setting of
2336C<low_water_mark> this will be called precisely when all data has been
2337written to the socket:
2338
2339 $handle->push_write (...);
2340 $handle->on_drain (sub {
2341 AE::log debug => "all data submitted to the kernel\n";
2342 undef $handle;
2343 });
2344
2345If you just want to queue some data and then signal EOF to the other side,
2346consider using C<< ->push_shutdown >> instead.
2347
2348=item I want to contact a TLS/SSL server, I don't care about security.
2349
2350If your TLS server is a pure TLS server (e.g. HTTPS) that only speaks TLS,
2351connect to it and then create the AnyEvent::Handle with the C<tls>
2352parameter:
2353
2354 tcp_connect $host, $port, sub {
2355 my ($fh) = @_;
2356
2357 my $handle = new AnyEvent::Handle
2358 fh => $fh,
2359 tls => "connect",
2360 on_error => sub { ... };
2361
2362 $handle->push_write (...);
1453 } 2363 };
1454}
1455 2364
1456=item AnyEvent::Handle::TLS_CTX 2365=item I want to contact a TLS/SSL server, I do care about security.
1457 2366
1458This function creates and returns the Net::SSLeay::CTX object used by 2367Then you should additionally enable certificate verification, including
1459default for TLS mode. 2368peername verification, if the protocol you use supports it (see
2369L<AnyEvent::TLS>, C<verify_peername>).
1460 2370
1461The context is created like this: 2371E.g. for HTTPS:
1462 2372
1463 Net::SSLeay::load_error_strings; 2373 tcp_connect $host, $port, sub {
1464 Net::SSLeay::SSLeay_add_ssl_algorithms; 2374 my ($fh) = @_;
1465 Net::SSLeay::randomize;
1466 2375
1467 my $CTX = Net::SSLeay::CTX_new; 2376 my $handle = new AnyEvent::Handle
2377 fh => $fh,
2378 peername => $host,
2379 tls => "connect",
2380 tls_ctx => { verify => 1, verify_peername => "https" },
2381 ...
1468 2382
1469 Net::SSLeay::CTX_set_options $CTX, Net::SSLeay::OP_ALL 2383Note that you must specify the hostname you connected to (or whatever
2384"peername" the protocol needs) as the C<peername> argument, otherwise no
2385peername verification will be done.
1470 2386
1471=cut 2387The above will use the system-dependent default set of trusted CA
2388certificates. If you want to check against a specific CA, add the
2389C<ca_file> (or C<ca_cert>) arguments to C<tls_ctx>:
1472 2390
1473our $TLS_CTX; 2391 tls_ctx => {
2392 verify => 1,
2393 verify_peername => "https",
2394 ca_file => "my-ca-cert.pem",
2395 },
1474 2396
1475sub TLS_CTX() { 2397=item I want to create a TLS/SSL server, how do I do that?
1476 $TLS_CTX || do {
1477 require Net::SSLeay;
1478 2398
1479 Net::SSLeay::load_error_strings (); 2399Well, you first need to get a server certificate and key. You have
1480 Net::SSLeay::SSLeay_add_ssl_algorithms (); 2400three options: a) ask a CA (buy one, use cacert.org etc.) b) create a
1481 Net::SSLeay::randomize (); 2401self-signed certificate (cheap. check the search engine of your choice,
2402there are many tutorials on the net) or c) make your own CA (tinyca2 is a
2403nice program for that purpose).
1482 2404
1483 $TLS_CTX = Net::SSLeay::CTX_new (); 2405Then create a file with your private key (in PEM format, see
2406L<AnyEvent::TLS>), followed by the certificate (also in PEM format). The
2407file should then look like this:
1484 2408
1485 Net::SSLeay::CTX_set_options ($TLS_CTX, Net::SSLeay::OP_ALL ()); 2409 -----BEGIN RSA PRIVATE KEY-----
2410 ...header data
2411 ... lots of base64'y-stuff
2412 -----END RSA PRIVATE KEY-----
1486 2413
1487 $TLS_CTX 2414 -----BEGIN CERTIFICATE-----
1488 } 2415 ... lots of base64'y-stuff
1489} 2416 -----END CERTIFICATE-----
2417
2418The important bits are the "PRIVATE KEY" and "CERTIFICATE" parts. Then
2419specify this file as C<cert_file>:
2420
2421 tcp_server undef, $port, sub {
2422 my ($fh) = @_;
2423
2424 my $handle = new AnyEvent::Handle
2425 fh => $fh,
2426 tls => "accept",
2427 tls_ctx => { cert_file => "my-server-keycert.pem" },
2428 ...
2429
2430When you have intermediate CA certificates that your clients might not
2431know about, just append them to the C<cert_file>.
1490 2432
1491=back 2433=back
2434
1492 2435
1493=head1 SUBCLASSING AnyEvent::Handle 2436=head1 SUBCLASSING AnyEvent::Handle
1494 2437
1495In many cases, you might want to subclass AnyEvent::Handle. 2438In many cases, you might want to subclass AnyEvent::Handle.
1496 2439
1513 2456
1514=item * all members not documented here and not prefixed with an underscore 2457=item * all members not documented here and not prefixed with an underscore
1515are free to use in subclasses. 2458are free to use in subclasses.
1516 2459
1517Of course, new versions of AnyEvent::Handle may introduce more "public" 2460Of course, new versions of AnyEvent::Handle may introduce more "public"
1518member variables, but thats just life, at least it is documented. 2461member variables, but that's just life. At least it is documented.
1519 2462
1520=back 2463=back
1521 2464
1522=head1 AUTHOR 2465=head1 AUTHOR
1523 2466

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines