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.28 by root, Sat May 24 22:27:11 2008 UTC vs.
Revision 1.142 by root, Mon Jul 6 20:24:47 2009 UTC

1package AnyEvent::Handle; 1package AnyEvent::Handle;
2 2
3no warnings; 3no warnings;
4use strict; 4use strict qw(subs vars);
5 5
6use AnyEvent (); 6use AnyEvent ();
7use AnyEvent::Util (); 7use AnyEvent::Util qw(WSAEWOULDBLOCK);
8use Scalar::Util (); 8use Scalar::Util ();
9use Carp (); 9use Carp ();
10use Fcntl (); 10use Fcntl ();
11use Errno qw/EAGAIN EINTR/; 11use Errno qw(EAGAIN EINTR);
12 12
13=head1 NAME 13=head1 NAME
14 14
15AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent 15AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent
16 16
17This module is experimental.
18
19=cut 17=cut
20 18
21our $VERSION = '0.04'; 19our $VERSION = 4.452;
22 20
23=head1 SYNOPSIS 21=head1 SYNOPSIS
24 22
25 use AnyEvent; 23 use AnyEvent;
26 use AnyEvent::Handle; 24 use AnyEvent::Handle;
27 25
28 my $cv = AnyEvent->condvar; 26 my $cv = AnyEvent->condvar;
29 27
30 my $ae_fh = AnyEvent::Handle->new (fh => \*STDIN); 28 my $handle =
31
32 #TODO
33
34 # or use the constructor to pass the callback:
35
36 my $ae_fh2 =
37 AnyEvent::Handle->new ( 29 AnyEvent::Handle->new (
38 fh => \*STDIN, 30 fh => \*STDIN,
39 on_eof => sub { 31 on_eof => sub {
40 $cv->broadcast; 32 $cv->send;
41 }, 33 },
42 #TODO
43 ); 34 );
44 35
45 $cv->wait; 36 # send some request line
37 $handle->push_write ("getinfo\015\012");
38
39 # read the response line
40 $handle->push_read (line => sub {
41 my ($handle, $line) = @_;
42 warn "read line <$line>\n";
43 $cv->send;
44 });
45
46 $cv->recv;
46 47
47=head1 DESCRIPTION 48=head1 DESCRIPTION
48 49
49This module is a helper module to make it easier to do event-based I/O on 50This module is a helper module to make it easier to do event-based I/O on
50filehandles. For utility functions for doing non-blocking connects and accepts 51filehandles. For utility functions for doing non-blocking connects and accepts
51on sockets see L<AnyEvent::Util>. 52on sockets see L<AnyEvent::Util>.
52 53
54The L<AnyEvent::Intro> tutorial contains some well-documented
55AnyEvent::Handle examples.
56
53In the following, when the documentation refers to of "bytes" then this 57In the following, when the documentation refers to of "bytes" then this
54means characters. As sysread and syswrite are used for all I/O, their 58means characters. As sysread and syswrite are used for all I/O, their
55treatment of characters applies to this module as well. 59treatment of characters applies to this module as well.
56 60
57All callbacks will be invoked with the handle object as their first 61All callbacks will be invoked with the handle object as their first
59 63
60=head1 METHODS 64=head1 METHODS
61 65
62=over 4 66=over 4
63 67
64=item B<new (%args)> 68=item $handle = B<new> AnyEvent::TLS fh => $filehandle, key => value...
65 69
66The constructor supports these arguments (all as key => value pairs). 70The constructor supports these arguments (all as C<< key => value >> pairs).
67 71
68=over 4 72=over 4
69 73
70=item fh => $filehandle [MANDATORY] 74=item fh => $filehandle [MANDATORY]
71 75
72The filehandle this L<AnyEvent::Handle> object will operate on. 76The filehandle this L<AnyEvent::Handle> object will operate on.
73 77
74NOTE: The filehandle will be set to non-blocking (using 78NOTE: The filehandle will be set to non-blocking mode (using
75AnyEvent::Util::fh_nonblocking). 79C<AnyEvent::Util::fh_nonblocking>) by the constructor and needs to stay in
80that mode.
76 81
77=item on_eof => $cb->($self) 82=item on_eof => $cb->($handle)
78 83
79Set the callback to be called on EOF. 84Set the callback to be called when an end-of-file condition is detected,
85i.e. in the case of a socket, when the other side has closed the
86connection cleanly.
80 87
88For sockets, this just means that the other side has stopped sending data,
89you can still try to write data, and, in fact, one can return from the EOF
90callback and continue writing data, as only the read part has been shut
91down.
92
81While not mandatory, it is highly recommended to set an eof callback, 93While not mandatory, it is I<highly> recommended to set an EOF callback,
82otherwise you might end up with a closed socket while you are still 94otherwise you might end up with a closed socket while you are still
83waiting for data. 95waiting for data.
84 96
85=item on_error => $cb->($self) 97If an EOF condition has been detected but no C<on_eof> callback has been
98set, then a fatal error will be raised with C<$!> set to <0>.
86 99
100=item on_error => $cb->($handle, $fatal, $message)
101
87This is the fatal error callback, that is called when, well, a fatal error 102This is the error callback, which is called when, well, some error
88occurs, such as not being able to resolve the hostname, failure to connect 103occured, such as not being able to resolve the hostname, failure to
89or a read error. 104connect or a read error.
90 105
91The object will not be in a usable state when this callback has been 106Some errors are fatal (which is indicated by C<$fatal> being true). On
92called. 107fatal errors the handle object will be shut down and will not be usable
108(but you are free to look at the current C<< ->rbuf >>). Examples of fatal
109errors are an EOF condition with active (but unsatisifable) read watchers
110(C<EPIPE>) or I/O errors.
111
112AnyEvent::Handle tries to find an appropriate error code for you to check
113against, but in some cases (TLS errors), this does not work well. It is
114recommended to always output the C<$message> argument in human-readable
115error messages (it's usually the same as C<"$!">).
116
117Non-fatal errors can be retried by simply returning, but it is recommended
118to simply ignore this parameter and instead abondon the handle object
119when this callback is invoked. Examples of non-fatal errors are timeouts
120C<ETIMEDOUT>) or badly-formatted data (C<EBADMSG>).
93 121
94On callback entrance, the value of C<$!> contains the operating system 122On callback entrance, the value of C<$!> contains the operating system
95error (or C<ENOSPC> or C<EPIPE>). 123error code (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT>, C<EBADMSG> or
124C<EPROTO>).
96 125
97While not mandatory, it is I<highly> recommended to set this callback, as 126While not mandatory, it is I<highly> recommended to set this callback, as
98you will not be notified of errors otherwise. The default simply calls 127you will not be notified of errors otherwise. The default simply calls
99die. 128C<croak>.
100 129
101=item on_read => $cb->($self) 130=item on_read => $cb->($handle)
102 131
103This sets the default read callback, which is called when data arrives 132This sets the default read callback, which is called when data arrives
104and no read request is in the queue. 133and no read request is in the queue (unlike read queue callbacks, this
134callback will only be called when at least one octet of data is in the
135read buffer).
105 136
106To access (and remove data from) the read buffer, use the C<< ->rbuf >> 137To access (and remove data from) the read buffer, use the C<< ->rbuf >>
107method or access the C<$self->{rbuf}> member directly. 138method or access the C<< $handle->{rbuf} >> member directly. Note that you
139must not enlarge or modify the read buffer, you can only remove data at
140the beginning from it.
108 141
109When an EOF condition is detected then AnyEvent::Handle will first try to 142When an EOF condition is detected then AnyEvent::Handle will first try to
110feed all the remaining data to the queued callbacks and C<on_read> before 143feed all the remaining data to the queued callbacks and C<on_read> before
111calling the C<on_eof> callback. If no progress can be made, then a fatal 144calling the C<on_eof> callback. If no progress can be made, then a fatal
112error will be raised (with C<$!> set to C<EPIPE>). 145error will be raised (with C<$!> set to C<EPIPE>).
113 146
114=item on_drain => $cb->() 147=item on_drain => $cb->($handle)
115 148
116This sets the callback that is called when the write buffer becomes empty 149This sets the callback that is called when the write buffer becomes empty
117(or when the callback is set and the buffer is empty already). 150(or when the callback is set and the buffer is empty already).
118 151
119To append to the write buffer, use the C<< ->push_write >> method. 152To append to the write buffer, use the C<< ->push_write >> method.
120 153
154This callback is useful when you don't want to put all of your write data
155into the queue at once, for example, when you want to write the contents
156of some file to the socket you might not want to read the whole file into
157memory and push it into the queue, but instead only read more data from
158the file when the write queue becomes empty.
159
160=item timeout => $fractional_seconds
161
162If non-zero, then this enables an "inactivity" timeout: whenever this many
163seconds pass without a successful read or write on the underlying file
164handle, the C<on_timeout> callback will be invoked (and if that one is
165missing, a non-fatal C<ETIMEDOUT> error will be raised).
166
167Note that timeout processing is also active when you currently do not have
168any outstanding read or write requests: If you plan to keep the connection
169idle then you should disable the timout temporarily or ignore the timeout
170in the C<on_timeout> callback, in which case AnyEvent::Handle will simply
171restart the timeout.
172
173Zero (the default) disables this timeout.
174
175=item on_timeout => $cb->($handle)
176
177Called whenever the inactivity timeout passes. If you return from this
178callback, then the timeout will be reset as if some activity had happened,
179so this condition is not fatal in any way.
180
121=item rbuf_max => <bytes> 181=item rbuf_max => <bytes>
122 182
123If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>) 183If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>)
124when the read buffer ever (strictly) exceeds this size. This is useful to 184when the read buffer ever (strictly) exceeds this size. This is useful to
125avoid denial-of-service attacks. 185avoid some forms of denial-of-service attacks.
126 186
127For example, a server accepting connections from untrusted sources should 187For example, a server accepting connections from untrusted sources should
128be configured to accept only so-and-so much data that it cannot act on 188be configured to accept only so-and-so much data that it cannot act on
129(for example, when expecting a line, an attacker could send an unlimited 189(for example, when expecting a line, an attacker could send an unlimited
130amount of data without a callback ever being called as long as the line 190amount of data without a callback ever being called as long as the line
131isn't finished). 191isn't finished).
132 192
193=item autocork => <boolean>
194
195When disabled (the default), then C<push_write> will try to immediately
196write the data to the handle, if possible. This avoids having to register
197a write watcher and wait for the next event loop iteration, but can
198be inefficient if you write multiple small chunks (on the wire, this
199disadvantage is usually avoided by your kernel's nagle algorithm, see
200C<no_delay>, but this option can save costly syscalls).
201
202When enabled, then writes will always be queued till the next event loop
203iteration. This is efficient when you do many small writes per iteration,
204but less efficient when you do a single write only per iteration (or when
205the write buffer often is full). It also increases write latency.
206
207=item no_delay => <boolean>
208
209When doing small writes on sockets, your operating system kernel might
210wait a bit for more data before actually sending it out. This is called
211the Nagle algorithm, and usually it is beneficial.
212
213In some situations you want as low a delay as possible, which can be
214accomplishd by setting this option to a true value.
215
216The default is your opertaing system's default behaviour (most likely
217enabled), this option explicitly enables or disables it, if possible.
218
133=item read_size => <bytes> 219=item read_size => <bytes>
134 220
135The default read block size (the amount of bytes this module will try to read 221The default read block size (the amount of bytes this module will
136on each [loop iteration). Default: C<4096>. 222try to read during each loop iteration, which affects memory
223requirements). Default: C<8192>.
137 224
138=item low_water_mark => <bytes> 225=item low_water_mark => <bytes>
139 226
140Sets the amount of bytes (default: C<0>) that make up an "empty" write 227Sets the amount of bytes (default: C<0>) that make up an "empty" write
141buffer: If the write reaches this size or gets even samller it is 228buffer: If the write reaches this size or gets even samller it is
142considered empty. 229considered empty.
143 230
231Sometimes it can be beneficial (for performance reasons) to add data to
232the write buffer before it is fully drained, but this is a rare case, as
233the operating system kernel usually buffers data as well, so the default
234is good in almost all cases.
235
236=item linger => <seconds>
237
238If non-zero (default: C<3600>), then the destructor of the
239AnyEvent::Handle object will check whether there is still outstanding
240write data and will install a watcher that will write this data to the
241socket. No errors will be reported (this mostly matches how the operating
242system treats outstanding data at socket close time).
243
244This will not work for partial TLS data that could not be encoded
245yet. This data will be lost. Calling the C<stoptls> method in time might
246help.
247
248=item peername => $string
249
250A string used to identify the remote site - usually the DNS hostname
251(I<not> IDN!) used to create the connection, rarely the IP address.
252
253Apart from being useful in error messages, this string is also used in TLS
254peername verification (see C<verify_peername> in L<AnyEvent::TLS>).
255
144=item tls => "accept" | "connect" | Net::SSLeay::SSL object 256=item tls => "accept" | "connect" | Net::SSLeay::SSL object
145 257
146When this parameter is given, it enables TLS (SSL) mode, that means it 258When this parameter is given, it enables TLS (SSL) mode, that means
147will start making tls handshake and will transparently encrypt/decrypt 259AnyEvent will start a TLS handshake as soon as the conenction has been
148data. 260established and will transparently encrypt/decrypt data afterwards.
261
262All TLS protocol errors will be signalled as C<EPROTO>, with an
263appropriate error message.
149 264
150TLS mode requires Net::SSLeay to be installed (it will be loaded 265TLS mode requires Net::SSLeay to be installed (it will be loaded
151automatically when you try to create a TLS handle). 266automatically when you try to create a TLS handle): this module doesn't
267have a dependency on that module, so if your module requires it, you have
268to add the dependency yourself.
152 269
153For the TLS server side, use C<accept>, and for the TLS client side of a 270Unlike TCP, TLS has a server and client side: for the TLS server side, use
154connection, use C<connect> mode. 271C<accept>, and for the TLS client side of a connection, use C<connect>
272mode.
155 273
156You can also provide your own TLS connection object, but you have 274You can also provide your own TLS connection object, but you have
157to make sure that you call either C<Net::SSLeay::set_connect_state> 275to make sure that you call either C<Net::SSLeay::set_connect_state>
158or C<Net::SSLeay::set_accept_state> on it before you pass it to 276or C<Net::SSLeay::set_accept_state> on it before you pass it to
159AnyEvent::Handle. 277AnyEvent::Handle. Also, this module will take ownership of this connection
278object.
160 279
280At some future point, AnyEvent::Handle might switch to another TLS
281implementation, then the option to use your own session object will go
282away.
283
284B<IMPORTANT:> since Net::SSLeay "objects" are really only integers,
285passing in the wrong integer will lead to certain crash. This most often
286happens when one uses a stylish C<< tls => 1 >> and is surprised about the
287segmentation fault.
288
161See the C<starttls> method if you need to start TLs negotiation later. 289See the C<< ->starttls >> method for when need to start TLS negotiation later.
162 290
163=item tls_ctx => $ssl_ctx 291=item tls_ctx => $anyevent_tls
164 292
165Use the given Net::SSLeay::CTX object to create the new TLS connection 293Use the given C<AnyEvent::TLS> object to create the new TLS connection
166(unless a connection object was specified directly). If this parameter is 294(unless a connection object was specified directly). If this parameter is
167missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>. 295missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>.
168 296
297Instead of an object, you can also specify a hash reference with C<< key
298=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a
299new TLS context object.
300
301=item on_starttls => $cb->($handle, $success)
302
303This callback will be invoked when the TLS/SSL handshake has finished. If
304C<$success> is true, then the TLS handshake succeeded, otherwise it failed
305(C<on_stoptls> will not be called in this case).
306
307The session in C<< $handle->{tls} >> can still be examined in this
308callback, even when the handshake was not successful.
309
310=item on_stoptls => $cb->($handle)
311
312When a SSLv3/TLS shutdown/close notify/EOF is detected and this callback is
313set, then it will be invoked after freeing the TLS session. If it is not,
314then a TLS shutdown condition will be treated like a normal EOF condition
315on the handle.
316
317The session in C<< $handle->{tls} >> can still be examined in this
318callback.
319
320This callback will only be called on TLS shutdowns, not when the
321underlying handle signals EOF.
322
323=item json => JSON or JSON::XS object
324
325This is the json coder object used by the C<json> read and write types.
326
327If you don't supply it, then AnyEvent::Handle will create and use a
328suitable one (on demand), which will write and expect UTF-8 encoded JSON
329texts.
330
331Note that you are responsible to depend on the JSON module if you want to
332use this functionality, as AnyEvent does not have a dependency itself.
333
169=back 334=back
170 335
171=cut 336=cut
172
173our (%RH, %WH);
174
175sub register_read_type($$) {
176 $RH{$_[0]} = $_[1];
177}
178
179sub register_write_type($$) {
180 $WH{$_[0]} = $_[1];
181}
182 337
183sub new { 338sub new {
184 my $class = shift; 339 my $class = shift;
185
186 my $self = bless { @_ }, $class; 340 my $self = bless { @_ }, $class;
187 341
188 $self->{fh} or Carp::croak "mandatory argument fh is missing"; 342 $self->{fh} or Carp::croak "mandatory argument fh is missing";
189 343
190 AnyEvent::Util::fh_nonblocking $self->{fh}, 1; 344 AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
191 345
192 if ($self->{tls}) { 346 $self->{_activity} = AnyEvent->now;
193 require Net::SSLeay; 347 $self->_timeout;
348
349 $self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay};
350
194 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx}); 351 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx})
195 } 352 if $self->{tls};
196 353
197 $self->on_eof (delete $self->{on_eof} ) if $self->{on_eof};
198 $self->on_error (delete $self->{on_error}) if $self->{on_error};
199 $self->on_drain (delete $self->{on_drain}) if $self->{on_drain}; 354 $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain};
200 $self->on_read (delete $self->{on_read} ) if $self->{on_read};
201 355
202 $self->start_read; 356 $self->start_read
357 if $self->{on_read};
203 358
204 $self 359 $self->{fh} && $self
205} 360}
206 361
207sub _shutdown { 362sub _shutdown {
208 my ($self) = @_; 363 my ($self) = @_;
209 364
210 delete $self->{rw}; 365 delete @$self{qw(_tw _rw _ww fh wbuf on_read _queue)};
211 delete $self->{ww}; 366 $self->{_eof} = 1; # tell starttls et. al to stop trying
212 delete $self->{fh};
213}
214 367
368 &_freetls;
369}
370
215sub error { 371sub _error {
216 my ($self) = @_; 372 my ($self, $errno, $fatal, $message) = @_;
217 373
218 {
219 local $!;
220 $self->_shutdown; 374 $self->_shutdown
221 } 375 if $fatal;
376
377 $! = $errno;
378 $message ||= "$!";
222 379
223 if ($self->{on_error}) { 380 if ($self->{on_error}) {
224 $self->{on_error}($self); 381 $self->{on_error}($self, $fatal, $message);
225 } else { 382 } elsif ($self->{fh}) {
226 die "AnyEvent::Handle uncaught fatal error: $!"; 383 Carp::croak "AnyEvent::Handle uncaught error: $message";
227 } 384 }
228} 385}
229 386
230=item $fh = $handle->fh 387=item $fh = $handle->fh
231 388
232This method returns the file handle of the L<AnyEvent::Handle> object. 389This method returns the file handle used to create the L<AnyEvent::Handle> object.
233 390
234=cut 391=cut
235 392
236sub fh { $_[0]->{fh} } 393sub fh { $_[0]{fh} }
237 394
238=item $handle->on_error ($cb) 395=item $handle->on_error ($cb)
239 396
240Replace the current C<on_error> callback (see the C<on_error> constructor argument). 397Replace the current C<on_error> callback (see the C<on_error> constructor argument).
241 398
253 410
254sub on_eof { 411sub on_eof {
255 $_[0]{on_eof} = $_[1]; 412 $_[0]{on_eof} = $_[1];
256} 413}
257 414
415=item $handle->on_timeout ($cb)
416
417Replace the current C<on_timeout> callback, or disables the callback (but
418not the timeout) if C<$cb> = C<undef>. See the C<timeout> constructor
419argument and method.
420
421=cut
422
423sub on_timeout {
424 $_[0]{on_timeout} = $_[1];
425}
426
427=item $handle->autocork ($boolean)
428
429Enables or disables the current autocork behaviour (see C<autocork>
430constructor argument). Changes will only take effect on the next write.
431
432=cut
433
434sub autocork {
435 $_[0]{autocork} = $_[1];
436}
437
438=item $handle->no_delay ($boolean)
439
440Enables or disables the C<no_delay> setting (see constructor argument of
441the same name for details).
442
443=cut
444
445sub no_delay {
446 $_[0]{no_delay} = $_[1];
447
448 eval {
449 local $SIG{__DIE__};
450 setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1];
451 };
452}
453
454=item $handle->on_starttls ($cb)
455
456Replace the current C<on_starttls> callback (see the C<on_starttls> constructor argument).
457
458=cut
459
460sub on_starttls {
461 $_[0]{on_starttls} = $_[1];
462}
463
464=item $handle->on_stoptls ($cb)
465
466Replace the current C<on_stoptls> callback (see the C<on_stoptls> constructor argument).
467
468=cut
469
470sub on_starttls {
471 $_[0]{on_stoptls} = $_[1];
472}
473
474#############################################################################
475
476=item $handle->timeout ($seconds)
477
478Configures (or disables) the inactivity timeout.
479
480=cut
481
482sub timeout {
483 my ($self, $timeout) = @_;
484
485 $self->{timeout} = $timeout;
486 $self->_timeout;
487}
488
489# reset the timeout watcher, as neccessary
490# also check for time-outs
491sub _timeout {
492 my ($self) = @_;
493
494 if ($self->{timeout}) {
495 my $NOW = AnyEvent->now;
496
497 # when would the timeout trigger?
498 my $after = $self->{_activity} + $self->{timeout} - $NOW;
499
500 # now or in the past already?
501 if ($after <= 0) {
502 $self->{_activity} = $NOW;
503
504 if ($self->{on_timeout}) {
505 $self->{on_timeout}($self);
506 } else {
507 $self->_error (&Errno::ETIMEDOUT);
508 }
509
510 # callback could have changed timeout value, optimise
511 return unless $self->{timeout};
512
513 # calculate new after
514 $after = $self->{timeout};
515 }
516
517 Scalar::Util::weaken $self;
518 return unless $self; # ->error could have destroyed $self
519
520 $self->{_tw} ||= AnyEvent->timer (after => $after, cb => sub {
521 delete $self->{_tw};
522 $self->_timeout;
523 });
524 } else {
525 delete $self->{_tw};
526 }
527}
528
258############################################################################# 529#############################################################################
259 530
260=back 531=back
261 532
262=head2 WRITE QUEUE 533=head2 WRITE QUEUE
283 my ($self, $cb) = @_; 554 my ($self, $cb) = @_;
284 555
285 $self->{on_drain} = $cb; 556 $self->{on_drain} = $cb;
286 557
287 $cb->($self) 558 $cb->($self)
288 if $cb && $self->{low_water_mark} >= length $self->{wbuf}; 559 if $cb && $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf});
289} 560}
290 561
291=item $handle->push_write ($data) 562=item $handle->push_write ($data)
292 563
293Queues the given scalar to be written. You can push as much data as you 564Queues the given scalar to be written. You can push as much data as you
297=cut 568=cut
298 569
299sub _drain_wbuf { 570sub _drain_wbuf {
300 my ($self) = @_; 571 my ($self) = @_;
301 572
302 unless ($self->{ww}) { 573 if (!$self->{_ww} && length $self->{wbuf}) {
574
303 Scalar::Util::weaken $self; 575 Scalar::Util::weaken $self;
576
304 my $cb = sub { 577 my $cb = sub {
305 my $len = syswrite $self->{fh}, $self->{wbuf}; 578 my $len = syswrite $self->{fh}, $self->{wbuf};
306 579
307 if ($len > 0) { 580 if ($len >= 0) {
308 substr $self->{wbuf}, 0, $len, ""; 581 substr $self->{wbuf}, 0, $len, "";
309 582
583 $self->{_activity} = AnyEvent->now;
584
310 $self->{on_drain}($self) 585 $self->{on_drain}($self)
311 if $self->{low_water_mark} >= length $self->{wbuf} 586 if $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf})
312 && $self->{on_drain}; 587 && $self->{on_drain};
313 588
314 delete $self->{ww} unless length $self->{wbuf}; 589 delete $self->{_ww} unless length $self->{wbuf};
315 } elsif ($! != EAGAIN && $! != EINTR) { 590 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {
316 $self->error; 591 $self->_error ($!, 1);
317 } 592 }
318 }; 593 };
319 594
595 # try to write data immediately
596 $cb->() unless $self->{autocork};
597
598 # if still data left in wbuf, we need to poll
320 $self->{ww} = AnyEvent->io (fh => $self->{fh}, poll => "w", cb => $cb); 599 $self->{_ww} = AnyEvent->io (fh => $self->{fh}, poll => "w", cb => $cb)
321 600 if length $self->{wbuf};
322 $cb->($self);
323 }; 601 };
602}
603
604our %WH;
605
606sub register_write_type($$) {
607 $WH{$_[0]} = $_[1];
324} 608}
325 609
326sub push_write { 610sub push_write {
327 my $self = shift; 611 my $self = shift;
328 612
613 if (@_ > 1) {
614 my $type = shift;
615
616 @_ = ($WH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_write")
617 ->($self, @_);
618 }
619
329 if ($self->{filter_w}) { 620 if ($self->{tls}) {
330 $self->{filter_w}->($self, \$_[0]); 621 $self->{_tls_wbuf} .= $_[0];
622
623 &_dotls ($self);
331 } else { 624 } else {
332 $self->{wbuf} .= $_[0]; 625 $self->{wbuf} .= $_[0];
333 $self->_drain_wbuf; 626 $self->_drain_wbuf;
334 } 627 }
335} 628}
336 629
630=item $handle->push_write (type => @args)
631
632Instead of formatting your data yourself, you can also let this module do
633the job by specifying a type and type-specific arguments.
634
635Predefined types are (if you have ideas for additional types, feel free to
636drop by and tell us):
637
638=over 4
639
640=item netstring => $string
641
642Formats the given value as netstring
643(http://cr.yp.to/proto/netstrings.txt, this is not a recommendation to use them).
644
645=cut
646
647register_write_type netstring => sub {
648 my ($self, $string) = @_;
649
650 (length $string) . ":$string,"
651};
652
653=item packstring => $format, $data
654
655An octet string prefixed with an encoded length. The encoding C<$format>
656uses the same format as a Perl C<pack> format, but must specify a single
657integer only (only one of C<cCsSlLqQiInNvVjJw> is allowed, plus an
658optional C<!>, C<< < >> or C<< > >> modifier).
659
660=cut
661
662register_write_type packstring => sub {
663 my ($self, $format, $string) = @_;
664
665 pack "$format/a*", $string
666};
667
668=item json => $array_or_hashref
669
670Encodes the given hash or array reference into a JSON object. Unless you
671provide your own JSON object, this means it will be encoded to JSON text
672in UTF-8.
673
674JSON objects (and arrays) are self-delimiting, so you can write JSON at
675one end of a handle and read them at the other end without using any
676additional framing.
677
678The generated JSON text is guaranteed not to contain any newlines: While
679this module doesn't need delimiters after or between JSON texts to be
680able to read them, many other languages depend on that.
681
682A simple RPC protocol that interoperates easily with others is to send
683JSON arrays (or objects, although arrays are usually the better choice as
684they mimic how function argument passing works) and a newline after each
685JSON text:
686
687 $handle->push_write (json => ["method", "arg1", "arg2"]); # whatever
688 $handle->push_write ("\012");
689
690An AnyEvent::Handle receiver would simply use the C<json> read type and
691rely on the fact that the newline will be skipped as leading whitespace:
692
693 $handle->push_read (json => sub { my $array = $_[1]; ... });
694
695Other languages could read single lines terminated by a newline and pass
696this line into their JSON decoder of choice.
697
698=cut
699
700register_write_type json => sub {
701 my ($self, $ref) = @_;
702
703 require JSON;
704
705 $self->{json} ? $self->{json}->encode ($ref)
706 : JSON::encode_json ($ref)
707};
708
709=item storable => $reference
710
711Freezes the given reference using L<Storable> and writes it to the
712handle. Uses the C<nfreeze> format.
713
714=cut
715
716register_write_type storable => sub {
717 my ($self, $ref) = @_;
718
719 require Storable;
720
721 pack "w/a*", Storable::nfreeze ($ref)
722};
723
724=back
725
726=item $handle->push_shutdown
727
728Sometimes you know you want to close the socket after writing your data
729before it was actually written. One way to do that is to replace your
730C<on_drain> handler by a callback that shuts down the socket (and set
731C<low_water_mark> to C<0>). This method is a shorthand for just that, and
732replaces the C<on_drain> callback with:
733
734 sub { shutdown $_[0]{fh}, 1 } # for push_shutdown
735
736This simply shuts down the write side and signals an EOF condition to the
737the peer.
738
739You can rely on the normal read queue and C<on_eof> handling
740afterwards. This is the cleanest way to close a connection.
741
742=cut
743
744sub push_shutdown {
745 my ($self) = @_;
746
747 delete $self->{low_water_mark};
748 $self->on_drain (sub { shutdown $_[0]{fh}, 1 });
749}
750
751=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args)
752
753This function (not method) lets you add your own types to C<push_write>.
754Whenever the given C<type> is used, C<push_write> will invoke the code
755reference with the handle object and the remaining arguments.
756
757The code reference is supposed to return a single octet string that will
758be appended to the write buffer.
759
760Note that this is a function, and all types registered this way will be
761global, so try to use unique names.
762
763=cut
764
337############################################################################# 765#############################################################################
338 766
339=back 767=back
340 768
341=head2 READ QUEUE 769=head2 READ QUEUE
347ways, the "simple" way, using only C<on_read> and the "complex" way, using 775ways, the "simple" way, using only C<on_read> and the "complex" way, using
348a queue. 776a queue.
349 777
350In the simple case, you just install an C<on_read> callback and whenever 778In the simple case, you just install an C<on_read> callback and whenever
351new data arrives, it will be called. You can then remove some data (if 779new data arrives, it will be called. You can then remove some data (if
352enough is there) from the read buffer (C<< $handle->rbuf >>) if you want 780enough is there) from the read buffer (C<< $handle->rbuf >>). Or you cna
353or not. 781leave the data there if you want to accumulate more (e.g. when only a
782partial message has been received so far).
354 783
355In the more complex case, you want to queue multiple callbacks. In this 784In the more complex case, you want to queue multiple callbacks. In this
356case, AnyEvent::Handle will call the first queued callback each time new 785case, AnyEvent::Handle will call the first queued callback each time new
357data arrives and removes it when it has done its job (see C<push_read>, 786data arrives (also the first time it is queued) and removes it when it has
358below). 787done its job (see C<push_read>, below).
359 788
360This way you can, for example, push three line-reads, followed by reading 789This way you can, for example, push three line-reads, followed by reading
361a chunk of data, and AnyEvent::Handle will execute them in order. 790a chunk of data, and AnyEvent::Handle will execute them in order.
362 791
363Example 1: EPP protocol parser. EPP sends 4 byte length info, followed by 792Example 1: EPP protocol parser. EPP sends 4 byte length info, followed by
364the specified number of bytes which give an XML datagram. 793the specified number of bytes which give an XML datagram.
365 794
366 # in the default state, expect some header bytes 795 # in the default state, expect some header bytes
367 $handle->on_read (sub { 796 $handle->on_read (sub {
368 # some data is here, now queue the length-header-read (4 octets) 797 # some data is here, now queue the length-header-read (4 octets)
369 shift->unshift_read_chunk (4, sub { 798 shift->unshift_read (chunk => 4, sub {
370 # header arrived, decode 799 # header arrived, decode
371 my $len = unpack "N", $_[1]; 800 my $len = unpack "N", $_[1];
372 801
373 # now read the payload 802 # now read the payload
374 shift->unshift_read_chunk ($len, sub { 803 shift->unshift_read (chunk => $len, sub {
375 my $xml = $_[1]; 804 my $xml = $_[1];
376 # handle xml 805 # handle xml
377 }); 806 });
378 }); 807 });
379 }); 808 });
380 809
381Example 2: Implement a client for a protocol that replies either with 810Example 2: Implement a client for a protocol that replies either with "OK"
382"OK" and another line or "ERROR" for one request, and 64 bytes for the 811and another line or "ERROR" for the first request that is sent, and 64
383second request. Due tot he availability of a full queue, we can just 812bytes for the second request. Due to the availability of a queue, we can
384pipeline sending both requests and manipulate the queue as necessary in 813just pipeline sending both requests and manipulate the queue as necessary
385the callbacks: 814in the callbacks.
386 815
387 # request one 816When the first callback is called and sees an "OK" response, it will
817C<unshift> another line-read. This line-read will be queued I<before> the
81864-byte chunk callback.
819
820 # request one, returns either "OK + extra line" or "ERROR"
388 $handle->push_write ("request 1\015\012"); 821 $handle->push_write ("request 1\015\012");
389 822
390 # we expect "ERROR" or "OK" as response, so push a line read 823 # we expect "ERROR" or "OK" as response, so push a line read
391 $handle->push_read_line (sub { 824 $handle->push_read (line => sub {
392 # if we got an "OK", we have to _prepend_ another line, 825 # if we got an "OK", we have to _prepend_ another line,
393 # so it will be read before the second request reads its 64 bytes 826 # so it will be read before the second request reads its 64 bytes
394 # which are already in the queue when this callback is called 827 # which are already in the queue when this callback is called
395 # we don't do this in case we got an error 828 # we don't do this in case we got an error
396 if ($_[1] eq "OK") { 829 if ($_[1] eq "OK") {
397 $_[0]->unshift_read_line (sub { 830 $_[0]->unshift_read (line => sub {
398 my $response = $_[1]; 831 my $response = $_[1];
399 ... 832 ...
400 }); 833 });
401 } 834 }
402 }); 835 });
403 836
404 # request two 837 # request two, simply returns 64 octets
405 $handle->push_write ("request 2\015\012"); 838 $handle->push_write ("request 2\015\012");
406 839
407 # simply read 64 bytes, always 840 # simply read 64 bytes, always
408 $handle->push_read_chunk (64, sub { 841 $handle->push_read (chunk => 64, sub {
409 my $response = $_[1]; 842 my $response = $_[1];
410 ... 843 ...
411 }); 844 });
412 845
413=over 4 846=over 4
414 847
415=cut 848=cut
416 849
417sub _drain_rbuf { 850sub _drain_rbuf {
418 my ($self) = @_; 851 my ($self) = @_;
852
853 local $self->{_in_drain} = 1;
419 854
420 if ( 855 if (
421 defined $self->{rbuf_max} 856 defined $self->{rbuf_max}
422 && $self->{rbuf_max} < length $self->{rbuf} 857 && $self->{rbuf_max} < length $self->{rbuf}
423 ) { 858 ) {
424 $! = &Errno::ENOSPC; return $self->error; 859 $self->_error (&Errno::ENOSPC, 1), return;
425 } 860 }
426 861
427 return if $self->{in_drain}; 862 while () {
428 local $self->{in_drain} = 1; 863 # we need to use a separate tls read buffer, as we must not receive data while
864 # we are draining the buffer, and this can only happen with TLS.
865 $self->{rbuf} .= delete $self->{_tls_rbuf} if exists $self->{_tls_rbuf};
429 866
430 while (my $len = length $self->{rbuf}) { 867 my $len = length $self->{rbuf};
431 no strict 'refs'; 868
432 if (my $cb = shift @{ $self->{queue} }) { 869 if (my $cb = shift @{ $self->{_queue} }) {
433 if (!$cb->($self)) { 870 unless ($cb->($self)) {
434 if ($self->{eof}) { 871 if ($self->{_eof}) {
435 # no progress can be made (not enough data and no data forthcoming) 872 # no progress can be made (not enough data and no data forthcoming)
436 $! = &Errno::EPIPE; return $self->error; 873 $self->_error (&Errno::EPIPE, 1), return;
437 } 874 }
438 875
439 unshift @{ $self->{queue} }, $cb; 876 unshift @{ $self->{_queue} }, $cb;
440 return; 877 last;
441 } 878 }
442 } elsif ($self->{on_read}) { 879 } elsif ($self->{on_read}) {
880 last unless $len;
881
443 $self->{on_read}($self); 882 $self->{on_read}($self);
444 883
445 if ( 884 if (
446 $self->{eof} # if no further data will arrive
447 && $len == length $self->{rbuf} # and no data has been consumed 885 $len == length $self->{rbuf} # if no data has been consumed
448 && !@{ $self->{queue} } # and the queue is still empty 886 && !@{ $self->{_queue} } # and the queue is still empty
449 && $self->{on_read} # and we still want to read data 887 && $self->{on_read} # but we still have on_read
450 ) { 888 ) {
889 # no further data will arrive
451 # then no progress can be made 890 # so no progress can be made
452 $! = &Errno::EPIPE; return $self->error; 891 $self->_error (&Errno::EPIPE, 1), return
892 if $self->{_eof};
893
894 last; # more data might arrive
453 } 895 }
454 } else { 896 } else {
455 # read side becomes idle 897 # read side becomes idle
456 delete $self->{rw}; 898 delete $self->{_rw} unless $self->{tls};
457 return; 899 last;
458 } 900 }
459 } 901 }
460 902
461 if ($self->{eof}) { 903 if ($self->{_eof}) {
462 $self->_shutdown; 904 if ($self->{on_eof}) {
463 $self->{on_eof}($self) 905 $self->{on_eof}($self)
464 if $self->{on_eof}; 906 } else {
907 $self->_error (0, 1, "Unexpected end-of-file");
908 }
909 }
910
911 # may need to restart read watcher
912 unless ($self->{_rw}) {
913 $self->start_read
914 if $self->{on_read} || @{ $self->{_queue} };
465 } 915 }
466} 916}
467 917
468=item $handle->on_read ($cb) 918=item $handle->on_read ($cb)
469 919
475 925
476sub on_read { 926sub on_read {
477 my ($self, $cb) = @_; 927 my ($self, $cb) = @_;
478 928
479 $self->{on_read} = $cb; 929 $self->{on_read} = $cb;
930 $self->_drain_rbuf if $cb && !$self->{_in_drain};
480} 931}
481 932
482=item $handle->rbuf 933=item $handle->rbuf
483 934
484Returns the read buffer (as a modifiable lvalue). 935Returns the read buffer (as a modifiable lvalue).
485 936
486You can access the read buffer directly as the C<< ->{rbuf} >> member, if 937You can access the read buffer directly as the C<< ->{rbuf} >>
487you want. 938member, if you want. However, the only operation allowed on the
939read buffer (apart from looking at it) is removing data from its
940beginning. Otherwise modifying or appending to it is not allowed and will
941lead to hard-to-track-down bugs.
488 942
489NOTE: The read buffer should only be used or modified if the C<on_read>, 943NOTE: The read buffer should only be used or modified if the C<on_read>,
490C<push_read> or C<unshift_read> methods are used. The other read methods 944C<push_read> or C<unshift_read> methods are used. The other read methods
491automatically manage the read buffer. 945automatically manage the read buffer.
492 946
515interested in (which can be none at all) and return a true value. After returning 969interested in (which can be none at all) and return a true value. After returning
516true, it will be removed from the queue. 970true, it will be removed from the queue.
517 971
518=cut 972=cut
519 973
974our %RH;
975
976sub register_read_type($$) {
977 $RH{$_[0]} = $_[1];
978}
979
520sub push_read { 980sub push_read {
521 my $self = shift; 981 my $self = shift;
522 my $cb = pop; 982 my $cb = pop;
523 983
524 if (@_) { 984 if (@_) {
526 986
527 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_read") 987 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_read")
528 ->($self, $cb, @_); 988 ->($self, $cb, @_);
529 } 989 }
530 990
531 push @{ $self->{queue} }, $cb; 991 push @{ $self->{_queue} }, $cb;
532 $self->_drain_rbuf; 992 $self->_drain_rbuf unless $self->{_in_drain};
533} 993}
534 994
535sub unshift_read { 995sub unshift_read {
536 my $self = shift; 996 my $self = shift;
537 my $cb = pop; 997 my $cb = pop;
542 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::unshift_read") 1002 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::unshift_read")
543 ->($self, $cb, @_); 1003 ->($self, $cb, @_);
544 } 1004 }
545 1005
546 1006
547 unshift @{ $self->{queue} }, $cb; 1007 unshift @{ $self->{_queue} }, $cb;
548 $self->_drain_rbuf; 1008 $self->_drain_rbuf unless $self->{_in_drain};
549} 1009}
550 1010
551=item $handle->push_read (type => @args, $cb) 1011=item $handle->push_read (type => @args, $cb)
552 1012
553=item $handle->unshift_read (type => @args, $cb) 1013=item $handle->unshift_read (type => @args, $cb)
554 1014
555Instead of providing a callback that parses the data itself you can chose 1015Instead of providing a callback that parses the data itself you can chose
556between a number of predefined parsing formats, for chunks of data, lines 1016between a number of predefined parsing formats, for chunks of data, lines
557etc. 1017etc.
558 1018
559The types currently supported are: 1019Predefined types are (if you have ideas for additional types, feel free to
1020drop by and tell us):
560 1021
561=over 4 1022=over 4
562 1023
563=item chunk => $octets, $cb->($self, $data) 1024=item chunk => $octets, $cb->($handle, $data)
564 1025
565Invoke the callback only once C<$octets> bytes have been read. Pass the 1026Invoke the callback only once C<$octets> bytes have been read. Pass the
566data read to the callback. The callback will never be called with less 1027data read to the callback. The callback will never be called with less
567data. 1028data.
568 1029
582 $cb->($_[0], substr $_[0]{rbuf}, 0, $len, ""); 1043 $cb->($_[0], substr $_[0]{rbuf}, 0, $len, "");
583 1 1044 1
584 } 1045 }
585}; 1046};
586 1047
587# compatibility with older API
588sub push_read_chunk {
589 $_[0]->push_read (chunk => $_[1], $_[2]);
590}
591
592sub unshift_read_chunk {
593 $_[0]->unshift_read (chunk => $_[1], $_[2]);
594}
595
596=item line => [$eol, ]$cb->($self, $line, $eol) 1048=item line => [$eol, ]$cb->($handle, $line, $eol)
597 1049
598The callback will be called only once a full line (including the end of 1050The callback will be called only once a full line (including the end of
599line marker, C<$eol>) has been read. This line (excluding the end of line 1051line marker, C<$eol>) has been read. This line (excluding the end of line
600marker) will be passed to the callback as second argument (C<$line>), and 1052marker) will be passed to the callback as second argument (C<$line>), and
601the end of line marker as the third argument (C<$eol>). 1053the end of line marker as the third argument (C<$eol>).
615=cut 1067=cut
616 1068
617register_read_type line => sub { 1069register_read_type line => sub {
618 my ($self, $cb, $eol) = @_; 1070 my ($self, $cb, $eol) = @_;
619 1071
620 $eol = qr|(\015?\012)| if @_ < 3; 1072 if (@_ < 3) {
1073 # this is more than twice as fast as the generic code below
1074 sub {
1075 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return;
1076
1077 $cb->($_[0], $1, $2);
1078 1
1079 }
1080 } else {
621 $eol = quotemeta $eol unless ref $eol; 1081 $eol = quotemeta $eol unless ref $eol;
622 $eol = qr|^(.*?)($eol)|s; 1082 $eol = qr|^(.*?)($eol)|s;
1083
1084 sub {
1085 $_[0]{rbuf} =~ s/$eol// or return;
1086
1087 $cb->($_[0], $1, $2);
1088 1
1089 }
1090 }
1091};
1092
1093=item regex => $accept[, $reject[, $skip], $cb->($handle, $data)
1094
1095Makes a regex match against the regex object C<$accept> and returns
1096everything up to and including the match.
1097
1098Example: read a single line terminated by '\n'.
1099
1100 $handle->push_read (regex => qr<\n>, sub { ... });
1101
1102If C<$reject> is given and not undef, then it determines when the data is
1103to be rejected: it is matched against the data when the C<$accept> regex
1104does not match and generates an C<EBADMSG> error when it matches. This is
1105useful to quickly reject wrong data (to avoid waiting for a timeout or a
1106receive buffer overflow).
1107
1108Example: expect a single decimal number followed by whitespace, reject
1109anything else (not the use of an anchor).
1110
1111 $handle->push_read (regex => qr<^[0-9]+\s>, qr<[^0-9]>, sub { ... });
1112
1113If C<$skip> is given and not C<undef>, then it will be matched against
1114the receive buffer when neither C<$accept> nor C<$reject> match,
1115and everything preceding and including the match will be accepted
1116unconditionally. This is useful to skip large amounts of data that you
1117know cannot be matched, so that the C<$accept> or C<$reject> regex do not
1118have to start matching from the beginning. This is purely an optimisation
1119and is usually worth only when you expect more than a few kilobytes.
1120
1121Example: expect a http header, which ends at C<\015\012\015\012>. Since we
1122expect the header to be very large (it isn't in practise, but...), we use
1123a skip regex to skip initial portions. The skip regex is tricky in that
1124it only accepts something not ending in either \015 or \012, as these are
1125required for the accept regex.
1126
1127 $handle->push_read (regex =>
1128 qr<\015\012\015\012>,
1129 undef, # no reject
1130 qr<^.*[^\015\012]>,
1131 sub { ... });
1132
1133=cut
1134
1135register_read_type regex => sub {
1136 my ($self, $cb, $accept, $reject, $skip) = @_;
1137
1138 my $data;
1139 my $rbuf = \$self->{rbuf};
623 1140
624 sub { 1141 sub {
625 $_[0]{rbuf} =~ s/$eol// or return; 1142 # accept
1143 if ($$rbuf =~ $accept) {
1144 $data .= substr $$rbuf, 0, $+[0], "";
1145 $cb->($self, $data);
1146 return 1;
1147 }
1148
1149 # reject
1150 if ($reject && $$rbuf =~ $reject) {
1151 $self->_error (&Errno::EBADMSG);
1152 }
626 1153
627 $cb->($_[0], $1, $2); 1154 # skip
1155 if ($skip && $$rbuf =~ $skip) {
1156 $data .= substr $$rbuf, 0, $+[0], "";
1157 }
1158
1159 ()
1160 }
1161};
1162
1163=item netstring => $cb->($handle, $string)
1164
1165A netstring (http://cr.yp.to/proto/netstrings.txt, this is not an endorsement).
1166
1167Throws an error with C<$!> set to EBADMSG on format violations.
1168
1169=cut
1170
1171register_read_type netstring => sub {
1172 my ($self, $cb) = @_;
1173
1174 sub {
1175 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) {
1176 if ($_[0]{rbuf} =~ /[^0-9]/) {
1177 $self->_error (&Errno::EBADMSG);
1178 }
1179 return;
1180 }
1181
1182 my $len = $1;
1183
1184 $self->unshift_read (chunk => $len, sub {
1185 my $string = $_[1];
1186 $_[0]->unshift_read (chunk => 1, sub {
1187 if ($_[1] eq ",") {
1188 $cb->($_[0], $string);
1189 } else {
1190 $self->_error (&Errno::EBADMSG);
1191 }
1192 });
1193 });
1194
628 1 1195 1
629 } 1196 }
630}; 1197};
631 1198
632# compatibility with older API 1199=item packstring => $format, $cb->($handle, $string)
633sub push_read_line {
634 my $self = shift;
635 $self->push_read (line => @_);
636}
637 1200
638sub unshift_read_line { 1201An octet string prefixed with an encoded length. The encoding C<$format>
639 my $self = shift; 1202uses the same format as a Perl C<pack> format, but must specify a single
640 $self->unshift_read (line => @_); 1203integer only (only one of C<cCsSlLqQiInNvVjJw> is allowed, plus an
641} 1204optional C<!>, C<< < >> or C<< > >> modifier).
1205
1206For example, DNS over TCP uses a prefix of C<n> (2 octet network order),
1207EPP uses a prefix of C<N> (4 octtes).
1208
1209Example: read a block of data prefixed by its length in BER-encoded
1210format (very efficient).
1211
1212 $handle->push_read (packstring => "w", sub {
1213 my ($handle, $data) = @_;
1214 });
1215
1216=cut
1217
1218register_read_type packstring => sub {
1219 my ($self, $cb, $format) = @_;
1220
1221 sub {
1222 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method
1223 defined (my $len = eval { unpack $format, $_[0]{rbuf} })
1224 or return;
1225
1226 $format = length pack $format, $len;
1227
1228 # bypass unshift if we already have the remaining chunk
1229 if ($format + $len <= length $_[0]{rbuf}) {
1230 my $data = substr $_[0]{rbuf}, $format, $len;
1231 substr $_[0]{rbuf}, 0, $format + $len, "";
1232 $cb->($_[0], $data);
1233 } else {
1234 # remove prefix
1235 substr $_[0]{rbuf}, 0, $format, "";
1236
1237 # read remaining chunk
1238 $_[0]->unshift_read (chunk => $len, $cb);
1239 }
1240
1241 1
1242 }
1243};
1244
1245=item json => $cb->($handle, $hash_or_arrayref)
1246
1247Reads a JSON object or array, decodes it and passes it to the
1248callback. When a parse error occurs, an C<EBADMSG> error will be raised.
1249
1250If a C<json> object was passed to the constructor, then that will be used
1251for the final decode, otherwise it will create a JSON coder expecting UTF-8.
1252
1253This read type uses the incremental parser available with JSON version
12542.09 (and JSON::XS version 2.2) and above. You have to provide a
1255dependency on your own: this module will load the JSON module, but
1256AnyEvent does not depend on it itself.
1257
1258Since JSON texts are fully self-delimiting, the C<json> read and write
1259types are an ideal simple RPC protocol: just exchange JSON datagrams. See
1260the C<json> write type description, above, for an actual example.
1261
1262=cut
1263
1264register_read_type json => sub {
1265 my ($self, $cb) = @_;
1266
1267 my $json = $self->{json} ||=
1268 eval { require JSON::XS; JSON::XS->new->utf8 }
1269 || do { require JSON; JSON->new->utf8 };
1270
1271 my $data;
1272 my $rbuf = \$self->{rbuf};
1273
1274 sub {
1275 my $ref = eval { $json->incr_parse ($self->{rbuf}) };
1276
1277 if ($ref) {
1278 $self->{rbuf} = $json->incr_text;
1279 $json->incr_text = "";
1280 $cb->($self, $ref);
1281
1282 1
1283 } elsif ($@) {
1284 # error case
1285 $json->incr_skip;
1286
1287 $self->{rbuf} = $json->incr_text;
1288 $json->incr_text = "";
1289
1290 $self->_error (&Errno::EBADMSG);
1291
1292 ()
1293 } else {
1294 $self->{rbuf} = "";
1295
1296 ()
1297 }
1298 }
1299};
1300
1301=item storable => $cb->($handle, $ref)
1302
1303Deserialises a L<Storable> frozen representation as written by the
1304C<storable> write type (BER-encoded length prefix followed by nfreeze'd
1305data).
1306
1307Raises C<EBADMSG> error if the data could not be decoded.
1308
1309=cut
1310
1311register_read_type storable => sub {
1312 my ($self, $cb) = @_;
1313
1314 require Storable;
1315
1316 sub {
1317 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method
1318 defined (my $len = eval { unpack "w", $_[0]{rbuf} })
1319 or return;
1320
1321 my $format = length pack "w", $len;
1322
1323 # bypass unshift if we already have the remaining chunk
1324 if ($format + $len <= length $_[0]{rbuf}) {
1325 my $data = substr $_[0]{rbuf}, $format, $len;
1326 substr $_[0]{rbuf}, 0, $format + $len, "";
1327 $cb->($_[0], Storable::thaw ($data));
1328 } else {
1329 # remove prefix
1330 substr $_[0]{rbuf}, 0, $format, "";
1331
1332 # read remaining chunk
1333 $_[0]->unshift_read (chunk => $len, sub {
1334 if (my $ref = eval { Storable::thaw ($_[1]) }) {
1335 $cb->($_[0], $ref);
1336 } else {
1337 $self->_error (&Errno::EBADMSG);
1338 }
1339 });
1340 }
1341
1342 1
1343 }
1344};
642 1345
643=back 1346=back
644 1347
1348=item AnyEvent::Handle::register_read_type type => $coderef->($handle, $cb, @args)
1349
1350This function (not method) lets you add your own types to C<push_read>.
1351
1352Whenever the given C<type> is used, C<push_read> will invoke the code
1353reference with the handle object, the callback and the remaining
1354arguments.
1355
1356The code reference is supposed to return a callback (usually a closure)
1357that works as a plain read callback (see C<< ->push_read ($cb) >>).
1358
1359It should invoke the passed callback when it is done reading (remember to
1360pass C<$handle> as first argument as all other callbacks do that).
1361
1362Note that this is a function, and all types registered this way will be
1363global, so try to use unique names.
1364
1365For examples, see the source of this module (F<perldoc -m AnyEvent::Handle>,
1366search for C<register_read_type>)).
1367
645=item $handle->stop_read 1368=item $handle->stop_read
646 1369
647=item $handle->start_read 1370=item $handle->start_read
648 1371
649In rare cases you actually do not want to read anything from the 1372In rare cases you actually do not want to read anything from the
650socket. In this case you can call C<stop_read>. Neither C<on_read> no 1373socket. In this case you can call C<stop_read>. Neither C<on_read> nor
651any queued callbacks will be executed then. To start reading again, call 1374any queued callbacks will be executed then. To start reading again, call
652C<start_read>. 1375C<start_read>.
653 1376
1377Note that AnyEvent::Handle will automatically C<start_read> for you when
1378you change the C<on_read> callback or push/unshift a read callback, and it
1379will automatically C<stop_read> for you when neither C<on_read> is set nor
1380there are any read requests in the queue.
1381
1382These methods will have no effect when in TLS mode (as TLS doesn't support
1383half-duplex connections).
1384
654=cut 1385=cut
655 1386
656sub stop_read { 1387sub stop_read {
657 my ($self) = @_; 1388 my ($self) = @_;
658 1389
659 delete $self->{rw}; 1390 delete $self->{_rw} unless $self->{tls};
660} 1391}
661 1392
662sub start_read { 1393sub start_read {
663 my ($self) = @_; 1394 my ($self) = @_;
664 1395
665 unless ($self->{rw} || $self->{eof}) { 1396 unless ($self->{_rw} || $self->{_eof}) {
666 Scalar::Util::weaken $self; 1397 Scalar::Util::weaken $self;
667 1398
668 $self->{rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub { 1399 $self->{_rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub {
669 my $rbuf = $self->{filter_r} ? \my $buf : \$self->{rbuf}; 1400 my $rbuf = \($self->{tls} ? my $buf : $self->{rbuf});
670 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf; 1401 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf;
671 1402
672 if ($len > 0) { 1403 if ($len > 0) {
673 $self->{filter_r} 1404 $self->{_activity} = AnyEvent->now;
674 ? $self->{filter_r}->($self, $rbuf) 1405
675 : $self->_drain_rbuf; 1406 if ($self->{tls}) {
1407 Net::SSLeay::BIO_write ($self->{_rbio}, $$rbuf);
1408
1409 &_dotls ($self);
1410 } else {
1411 $self->_drain_rbuf unless $self->{_in_drain};
1412 }
676 1413
677 } elsif (defined $len) { 1414 } elsif (defined $len) {
678 delete $self->{rw}; 1415 delete $self->{_rw};
679 $self->{eof} = 1; 1416 $self->{_eof} = 1;
680 $self->_drain_rbuf; 1417 $self->_drain_rbuf unless $self->{_in_drain};
681 1418
682 } elsif ($! != EAGAIN && $! != EINTR) { 1419 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {
683 return $self->error; 1420 return $self->_error ($!, 1);
684 } 1421 }
685 }); 1422 });
686 } 1423 }
687} 1424}
688 1425
1426our $ERROR_SYSCALL;
1427our $ERROR_WANT_READ;
1428
1429sub _tls_error {
1430 my ($self, $err) = @_;
1431
1432 return $self->_error ($!, 1)
1433 if $err == Net::SSLeay::ERROR_SYSCALL ();
1434
1435 my $err =Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ());
1436
1437 # reduce error string to look less scary
1438 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /;
1439
1440 $self->_error (&Errno::EPROTO, 1, $err);
1441}
1442
1443# poll the write BIO and send the data if applicable
1444# also decode read data if possible
1445# this is basiclaly our TLS state machine
1446# more efficient implementations are possible with openssl,
1447# but not with the buggy and incomplete Net::SSLeay.
689sub _dotls { 1448sub _dotls {
690 my ($self) = @_; 1449 my ($self) = @_;
691 1450
1451 my $tmp;
1452
692 if (length $self->{tls_wbuf}) { 1453 if (length $self->{_tls_wbuf}) {
693 while ((my $len = Net::SSLeay::write ($self->{tls}, $self->{tls_wbuf})) > 0) { 1454 while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) {
694 substr $self->{tls_wbuf}, 0, $len, ""; 1455 substr $self->{_tls_wbuf}, 0, $tmp, "";
695 } 1456 }
696 }
697 1457
1458 $tmp = Net::SSLeay::get_error ($self->{tls}, $tmp);
1459 return $self->_tls_error ($tmp)
1460 if $tmp != $ERROR_WANT_READ
1461 && ($tmp != $ERROR_SYSCALL || $!);
1462 }
1463
698 if (defined (my $buf = Net::SSLeay::BIO_read ($self->{tls_wbio}))) { 1464 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
1465 unless (length $tmp) {
1466 &_freetls;
1467 if ($self->{on_stoptls}) {
1468 $self->{on_stoptls}($self);
1469 return;
1470 } else {
1471 # let's treat SSL-eof as we treat normal EOF
1472 delete $self->{_rw};
1473 $self->{_eof} = 1;
1474 }
1475 }
1476
1477 $self->{_tls_rbuf} .= $tmp;
1478 $self->_drain_rbuf unless $self->{_in_drain};
1479 $self->{tls} or return; # tls session might have gone away in callback
1480 }
1481
1482 $tmp = Net::SSLeay::get_error ($self->{tls}, -1);
1483 return $self->_tls_error ($tmp)
1484 if $tmp != $ERROR_WANT_READ
1485 && ($tmp != $ERROR_SYSCALL || $!);
1486
1487 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {
699 $self->{wbuf} .= $buf; 1488 $self->{wbuf} .= $tmp;
700 $self->_drain_wbuf; 1489 $self->_drain_wbuf;
701 } 1490 }
702 1491
703 while (defined (my $buf = Net::SSLeay::read ($self->{tls}))) { 1492 $self->{_on_starttls}
704 $self->{rbuf} .= $buf; 1493 and Net::SSLeay::state ($self->{tls}) == Net::SSLeay::ST_OK ()
705 $self->_drain_rbuf; 1494 and (delete $self->{_on_starttls})->($self, 1);
706 }
707
708 my $err = Net::SSLeay::get_error ($self->{tls}, -1);
709
710 if ($err!= Net::SSLeay::ERROR_WANT_READ ()) {
711 if ($err == Net::SSLeay::ERROR_SYSCALL ()) {
712 $self->error;
713 } elsif ($err == Net::SSLeay::ERROR_SSL ()) {
714 $! = &Errno::EIO;
715 $self->error;
716 }
717
718 # all others are fine for our purposes
719 }
720} 1495}
721 1496
722=item $handle->starttls ($tls[, $tls_ctx]) 1497=item $handle->starttls ($tls[, $tls_ctx])
723 1498
724Instead of starting TLS negotiation immediately when the AnyEvent::Handle 1499Instead of starting TLS negotiation immediately when the AnyEvent::Handle
726C<starttls>. 1501C<starttls>.
727 1502
728The first argument is the same as the C<tls> constructor argument (either 1503The first argument is the same as the C<tls> constructor argument (either
729C<"connect">, C<"accept"> or an existing Net::SSLeay object). 1504C<"connect">, C<"accept"> or an existing Net::SSLeay object).
730 1505
731The second argument is the optional C<Net::SSLeay::CTX> object that is 1506The second argument is the optional C<AnyEvent::TLS> object that is used
732used when AnyEvent::Handle has to create its own TLS connection object. 1507when AnyEvent::Handle has to create its own TLS connection object, or
1508a hash reference with C<< key => value >> pairs that will be used to
1509construct a new context.
733 1510
734=cut 1511The TLS connection object will end up in C<< $handle->{tls} >>, the TLS
1512context in C<< $handle->{tls_ctx} >> after this call and can be used or
1513changed to your liking. Note that the handshake might have already started
1514when this function returns.
735 1515
736# TODO: maybe document... 1516If it an error to start a TLS handshake more than once per
1517AnyEvent::Handle object (this is due to bugs in OpenSSL).
1518
1519=cut
1520
1521our %TLS_CACHE; #TODO not yet documented, should we?
1522
737sub starttls { 1523sub starttls {
738 my ($self, $ssl, $ctx) = @_; 1524 my ($self, $ssl, $ctx) = @_;
739 1525
740 $self->stoptls; 1526 require Net::SSLeay;
741 1527
742 if ($ssl eq "accept") { 1528 Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object"
743 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ()); 1529 if $self->{tls};
744 Net::SSLeay::set_accept_state ($ssl); 1530
745 } elsif ($ssl eq "connect") { 1531 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL ();
746 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ()); 1532 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ ();
747 Net::SSLeay::set_connect_state ($ssl); 1533
1534 $ctx ||= $self->{tls_ctx};
1535
1536 if ("HASH" eq ref $ctx) {
1537 require AnyEvent::TLS;
1538
1539 local $Carp::CarpLevel = 1; # skip ourselves when creating a new context
1540
1541 if ($ctx->{cache}) {
1542 my $key = $ctx+0;
1543 $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx;
1544 } else {
1545 $ctx = new AnyEvent::TLS %$ctx;
1546 }
1547 }
748 } 1548
749 1549 $self->{tls_ctx} = $ctx || TLS_CTX ();
750 $self->{tls} = $ssl; 1550 $self->{tls} = $ssl = $self->{tls_ctx}->_get_session ($ssl, $self, $self->{peername});
751 1551
752 # basically, this is deep magic (because SSL_read should have the same issues) 1552 # basically, this is deep magic (because SSL_read should have the same issues)
753 # but the openssl maintainers basically said: "trust us, it just works". 1553 # but the openssl maintainers basically said: "trust us, it just works".
754 # (unfortunately, we have to hardcode constants because the abysmally misdesigned 1554 # (unfortunately, we have to hardcode constants because the abysmally misdesigned
755 # and mismaintained ssleay-module doesn't even offer them). 1555 # and mismaintained ssleay-module doesn't even offer them).
756 # http://www.mail-archive.com/openssl-dev@openssl.org/msg22420.html 1556 # http://www.mail-archive.com/openssl-dev@openssl.org/msg22420.html
1557 #
1558 # in short: this is a mess.
1559 #
1560 # note that we do not try to keep the length constant between writes as we are required to do.
1561 # we assume that most (but not all) of this insanity only applies to non-blocking cases,
1562 # and we drive openssl fully in blocking mode here. Or maybe we don't - openssl seems to
1563 # have identity issues in that area.
757 Net::SSLeay::CTX_set_mode ($self->{tls}, 1564# Net::SSLeay::CTX_set_mode ($ssl,
758 (eval { Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1) 1565# (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1)
759 | (eval { Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2)); 1566# | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2));
1567 Net::SSLeay::CTX_set_mode ($ssl, 1|2);
760 1568
761 $self->{tls_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1569 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
762 $self->{tls_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1570 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
763 1571
764 Net::SSLeay::set_bio ($ssl, $self->{tls_rbio}, $self->{tls_wbio}); 1572 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio});
765 1573
766 $self->{filter_w} = sub { 1574 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) }
767 $_[0]{tls_wbuf} .= ${$_[1]}; 1575 if exists $self->{on_starttls};
768 &_dotls; 1576
769 }; 1577 &_dotls; # need to trigger the initial handshake
770 $self->{filter_r} = sub { 1578 $self->start_read; # make sure we actually do read
771 Net::SSLeay::BIO_write ($_[0]{tls_rbio}, ${$_[1]});
772 &_dotls;
773 };
774} 1579}
775 1580
776=item $handle->stoptls 1581=item $handle->stoptls
777 1582
778Destroys the SSL connection, if any. Partial read or write data will be 1583Shuts down the SSL connection - this makes a proper EOF handshake by
779lost. 1584sending a close notify to the other side, but since OpenSSL doesn't
1585support non-blocking shut downs, it is not possible to re-use the stream
1586afterwards.
780 1587
781=cut 1588=cut
782 1589
783sub stoptls { 1590sub stoptls {
784 my ($self) = @_; 1591 my ($self) = @_;
785 1592
786 Net::SSLeay::free (delete $self->{tls}) if $self->{tls}; 1593 if ($self->{tls}) {
787 delete $self->{tls_rbio}; 1594 Net::SSLeay::shutdown ($self->{tls});
788 delete $self->{tls_wbio}; 1595
789 delete $self->{tls_wbuf}; 1596 &_dotls;
790 delete $self->{filter_r}; 1597
791 delete $self->{filter_w}; 1598# # we don't give a shit. no, we do, but we can't. no...#d#
1599# # we, we... have to use openssl :/#d#
1600# &_freetls;#d#
1601 }
1602}
1603
1604sub _freetls {
1605 my ($self) = @_;
1606
1607 return unless $self->{tls};
1608
1609 $self->{_on_starttls}
1610 and (delete $self->{_on_starttls})->($self, undef);
1611
1612 $self->{tls_ctx}->_put_session (delete $self->{tls});
1613
1614 delete @$self{qw(_rbio _wbio _tls_wbuf)};
792} 1615}
793 1616
794sub DESTROY { 1617sub DESTROY {
795 my $self = shift; 1618 my ($self) = @_;
796 1619
797 $self->stoptls; 1620 &_freetls;
1621
1622 my $linger = exists $self->{linger} ? $self->{linger} : 3600;
1623
1624 if ($linger && length $self->{wbuf}) {
1625 my $fh = delete $self->{fh};
1626 my $wbuf = delete $self->{wbuf};
1627
1628 my @linger;
1629
1630 push @linger, AnyEvent->io (fh => $fh, poll => "w", cb => sub {
1631 my $len = syswrite $fh, $wbuf, length $wbuf;
1632
1633 if ($len > 0) {
1634 substr $wbuf, 0, $len, "";
1635 } else {
1636 @linger = (); # end
1637 }
1638 });
1639 push @linger, AnyEvent->timer (after => $linger, cb => sub {
1640 @linger = ();
1641 });
1642 }
1643}
1644
1645=item $handle->destroy
1646
1647Shuts down the handle object as much as possible - this call ensures that
1648no further callbacks will be invoked and as many resources as possible
1649will be freed. You must not call any methods on the object afterwards.
1650
1651Normally, you can just "forget" any references to an AnyEvent::Handle
1652object and it will simply shut down. This works in fatal error and EOF
1653callbacks, as well as code outside. It does I<NOT> work in a read or write
1654callback, so when you want to destroy the AnyEvent::Handle object from
1655within such an callback. You I<MUST> call C<< ->destroy >> explicitly in
1656that case.
1657
1658The handle might still linger in the background and write out remaining
1659data, as specified by the C<linger> option, however.
1660
1661=cut
1662
1663sub destroy {
1664 my ($self) = @_;
1665
1666 $self->DESTROY;
1667 %$self = ();
798} 1668}
799 1669
800=item AnyEvent::Handle::TLS_CTX 1670=item AnyEvent::Handle::TLS_CTX
801 1671
802This function creates and returns the Net::SSLeay::CTX object used by 1672This function creates and returns the AnyEvent::TLS object used by default
803default for TLS mode. 1673for TLS mode.
804 1674
805The context is created like this: 1675The context is created by calling L<AnyEvent::TLS> without any arguments.
806
807 Net::SSLeay::load_error_strings;
808 Net::SSLeay::SSLeay_add_ssl_algorithms;
809 Net::SSLeay::randomize;
810
811 my $CTX = Net::SSLeay::CTX_new;
812
813 Net::SSLeay::CTX_set_options $CTX, Net::SSLeay::OP_ALL
814 1676
815=cut 1677=cut
816 1678
817our $TLS_CTX; 1679our $TLS_CTX;
818 1680
819sub TLS_CTX() { 1681sub TLS_CTX() {
820 $TLS_CTX || do { 1682 $TLS_CTX ||= do {
821 require Net::SSLeay; 1683 require AnyEvent::TLS;
822 1684
823 Net::SSLeay::load_error_strings (); 1685 new AnyEvent::TLS
824 Net::SSLeay::SSLeay_add_ssl_algorithms ();
825 Net::SSLeay::randomize ();
826
827 $TLS_CTX = Net::SSLeay::CTX_new ();
828
829 Net::SSLeay::CTX_set_options ($TLS_CTX, Net::SSLeay::OP_ALL ());
830
831 $TLS_CTX
832 } 1686 }
833} 1687}
834 1688
835=back 1689=back
836 1690
1691
1692=head1 NONFREQUENTLY ASKED QUESTIONS
1693
1694=over 4
1695
1696=item I C<undef> the AnyEvent::Handle reference inside my callback and
1697still get further invocations!
1698
1699That's because AnyEvent::Handle keeps a reference to itself when handling
1700read or write callbacks.
1701
1702It is only safe to "forget" the reference inside EOF or error callbacks,
1703from within all other callbacks, you need to explicitly call the C<<
1704->destroy >> method.
1705
1706=item I get different callback invocations in TLS mode/Why can't I pause
1707reading?
1708
1709Unlike, say, TCP, TLS connections do not consist of two independent
1710communication channels, one for each direction. Or put differently. The
1711read and write directions are not independent of each other: you cannot
1712write data unless you are also prepared to read, and vice versa.
1713
1714This can mean than, in TLS mode, you might get C<on_error> or C<on_eof>
1715callback invocations when you are not expecting any read data - the reason
1716is that AnyEvent::Handle always reads in TLS mode.
1717
1718During the connection, you have to make sure that you always have a
1719non-empty read-queue, or an C<on_read> watcher. At the end of the
1720connection (or when you no longer want to use it) you can call the
1721C<destroy> method.
1722
1723=item How do I read data until the other side closes the connection?
1724
1725If you just want to read your data into a perl scalar, the easiest way
1726to achieve this is by setting an C<on_read> callback that does nothing,
1727clearing the C<on_eof> callback and in the C<on_error> callback, the data
1728will be in C<$_[0]{rbuf}>:
1729
1730 $handle->on_read (sub { });
1731 $handle->on_eof (undef);
1732 $handle->on_error (sub {
1733 my $data = delete $_[0]{rbuf};
1734 undef $handle;
1735 });
1736
1737The reason to use C<on_error> is that TCP connections, due to latencies
1738and packets loss, might get closed quite violently with an error, when in
1739fact, all data has been received.
1740
1741It is usually better to use acknowledgements when transferring data,
1742to make sure the other side hasn't just died and you got the data
1743intact. This is also one reason why so many internet protocols have an
1744explicit QUIT command.
1745
1746=item I don't want to destroy the handle too early - how do I wait until
1747all data has been written?
1748
1749After writing your last bits of data, set the C<on_drain> callback
1750and destroy the handle in there - with the default setting of
1751C<low_water_mark> this will be called precisely when all data has been
1752written to the socket:
1753
1754 $handle->push_write (...);
1755 $handle->on_drain (sub {
1756 warn "all data submitted to the kernel\n";
1757 undef $handle;
1758 });
1759
1760=back
1761
1762
1763=head1 SUBCLASSING AnyEvent::Handle
1764
1765In many cases, you might want to subclass AnyEvent::Handle.
1766
1767To make this easier, a given version of AnyEvent::Handle uses these
1768conventions:
1769
1770=over 4
1771
1772=item * all constructor arguments become object members.
1773
1774At least initially, when you pass a C<tls>-argument to the constructor it
1775will end up in C<< $handle->{tls} >>. Those members might be changed or
1776mutated later on (for example C<tls> will hold the TLS connection object).
1777
1778=item * other object member names are prefixed with an C<_>.
1779
1780All object members not explicitly documented (internal use) are prefixed
1781with an underscore character, so the remaining non-C<_>-namespace is free
1782for use for subclasses.
1783
1784=item * all members not documented here and not prefixed with an underscore
1785are free to use in subclasses.
1786
1787Of course, new versions of AnyEvent::Handle may introduce more "public"
1788member variables, but thats just life, at least it is documented.
1789
1790=back
1791
837=head1 AUTHOR 1792=head1 AUTHOR
838 1793
839Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>. 1794Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>.
840 1795
841=cut 1796=cut

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines