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.36 by root, Mon May 26 18:26:52 2008 UTC vs.
Revision 1.60 by root, Thu Jun 5 18:30:08 2008 UTC

… …
2 2
3no warnings; 3no warnings;
4use strict; 4use strict;
5 5
6use AnyEvent (); 6use AnyEvent ();
7use AnyEvent::Util qw(WSAWOULDBLOCK); 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
17=cut 17=cut
18 18
19our $VERSION = '0.04'; 19our $VERSION = 4.14;
20 20
21=head1 SYNOPSIS 21=head1 SYNOPSIS
22 22
23 use AnyEvent; 23 use AnyEvent;
24 use AnyEvent::Handle; 24 use AnyEvent::Handle;
… …
73The filehandle this L<AnyEvent::Handle> object will operate on. 73The filehandle this L<AnyEvent::Handle> object will operate on.
74 74
75NOTE: The filehandle will be set to non-blocking (using 75NOTE: The filehandle will be set to non-blocking (using
76AnyEvent::Util::fh_nonblocking). 76AnyEvent::Util::fh_nonblocking).
77 77
78=item on_eof => $cb->($self) 78=item on_eof => $cb->($handle)
79 79
80Set the callback to be called on EOF. 80Set the callback to be called when an end-of-file condition is detcted,
81i.e. in the case of a socket, when the other side has closed the
82connection cleanly.
81 83
82While not mandatory, it is highly recommended to set an eof callback, 84While not mandatory, it is highly recommended to set an eof callback,
83otherwise you might end up with a closed socket while you are still 85otherwise you might end up with a closed socket while you are still
84waiting for data. 86waiting for data.
85 87
86=item on_error => $cb->($self) 88=item on_error => $cb->($handle, $fatal)
87 89
88This is the fatal error callback, that is called when, well, a fatal error 90This is the error callback, which is called when, well, some error
89occurs, such as not being able to resolve the hostname, failure to connect 91occured, such as not being able to resolve the hostname, failure to
90or a read error. 92connect or a read error.
91 93
92The object will not be in a usable state when this callback has been 94Some errors are fatal (which is indicated by C<$fatal> being true). On
93called. 95fatal errors the handle object will be shut down and will not be
96usable. Non-fatal errors can be retried by simply returning, but it is
97recommended to simply ignore this parameter and instead abondon the handle
98object when this callback is invoked.
94 99
95On callback entrance, the value of C<$!> contains the operating system 100On callback entrance, the value of C<$!> contains the operating system
96error (or C<ENOSPC>, C<EPIPE> or C<EBADMSG>). 101error (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT> or C<EBADMSG>).
97 102
98While not mandatory, it is I<highly> recommended to set this callback, as 103While not mandatory, it is I<highly> recommended to set this callback, as
99you will not be notified of errors otherwise. The default simply calls 104you will not be notified of errors otherwise. The default simply calls
100die. 105C<croak>.
101 106
102=item on_read => $cb->($self) 107=item on_read => $cb->($handle)
103 108
104This sets the default read callback, which is called when data arrives 109This sets the default read callback, which is called when data arrives
105and no read request is in the queue. 110and no read request is in the queue.
106 111
107To access (and remove data from) the read buffer, use the C<< ->rbuf >> 112To access (and remove data from) the read buffer, use the C<< ->rbuf >>
108method or access the C<$self->{rbuf}> member directly. 113method or access the C<$handle->{rbuf}> member directly.
109 114
110When an EOF condition is detected then AnyEvent::Handle will first try to 115When an EOF condition is detected then AnyEvent::Handle will first try to
111feed all the remaining data to the queued callbacks and C<on_read> before 116feed all the remaining data to the queued callbacks and C<on_read> before
112calling the C<on_eof> callback. If no progress can be made, then a fatal 117calling the C<on_eof> callback. If no progress can be made, then a fatal
113error will be raised (with C<$!> set to C<EPIPE>). 118error will be raised (with C<$!> set to C<EPIPE>).
114 119
115=item on_drain => $cb->() 120=item on_drain => $cb->($handle)
116 121
117This sets the callback that is called when the write buffer becomes empty 122This sets the callback that is called when the write buffer becomes empty
118(or when the callback is set and the buffer is empty already). 123(or when the callback is set and the buffer is empty already).
119 124
120To append to the write buffer, use the C<< ->push_write >> method. 125To append to the write buffer, use the C<< ->push_write >> method.
126
127=item timeout => $fractional_seconds
128
129If non-zero, then this enables an "inactivity" timeout: whenever this many
130seconds pass without a successful read or write on the underlying file
131handle, the C<on_timeout> callback will be invoked (and if that one is
132missing, an C<ETIMEDOUT> error will be raised).
133
134Note that timeout processing is also active when you currently do not have
135any outstanding read or write requests: If you plan to keep the connection
136idle then you should disable the timout temporarily or ignore the timeout
137in the C<on_timeout> callback.
138
139Zero (the default) disables this timeout.
140
141=item on_timeout => $cb->($handle)
142
143Called whenever the inactivity timeout passes. If you return from this
144callback, then the timeout will be reset as if some activity had happened,
145so this condition is not fatal in any way.
121 146
122=item rbuf_max => <bytes> 147=item rbuf_max => <bytes>
123 148
124If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>) 149If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>)
125when the read buffer ever (strictly) exceeds this size. This is useful to 150when the read buffer ever (strictly) exceeds this size. This is useful to
… …
132isn't finished). 157isn't finished).
133 158
134=item read_size => <bytes> 159=item read_size => <bytes>
135 160
136The default read block size (the amount of bytes this module will try to read 161The default read block size (the amount of bytes this module will try to read
137on each [loop iteration). Default: C<4096>. 162during each (loop iteration). Default: C<8192>.
138 163
139=item low_water_mark => <bytes> 164=item low_water_mark => <bytes>
140 165
141Sets the amount of bytes (default: C<0>) that make up an "empty" write 166Sets the amount of bytes (default: C<0>) that make up an "empty" write
142buffer: If the write reaches this size or gets even samller it is 167buffer: If the write reaches this size or gets even samller it is
… …
165 190
166Use the given Net::SSLeay::CTX object to create the new TLS connection 191Use the given Net::SSLeay::CTX object to create the new TLS connection
167(unless a connection object was specified directly). If this parameter is 192(unless a connection object was specified directly). If this parameter is
168missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>. 193missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>.
169 194
195=item json => JSON or JSON::XS object
196
197This is the json coder object used by the C<json> read and write types.
198
199If you don't supply it, then AnyEvent::Handle will create and use a
200suitable one, which will write and expect UTF-8 encoded JSON texts.
201
202Note that you are responsible to depend on the JSON module if you want to
203use this functionality, as AnyEvent does not have a dependency itself.
204
205=item filter_r => $cb
206
207=item filter_w => $cb
208
209These exist, but are undocumented at this time.
210
170=back 211=back
171 212
172=cut 213=cut
173 214
174sub new { 215sub new {
… …
183 if ($self->{tls}) { 224 if ($self->{tls}) {
184 require Net::SSLeay; 225 require Net::SSLeay;
185 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx}); 226 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx});
186 } 227 }
187 228
188 $self->on_eof (delete $self->{on_eof} ) if $self->{on_eof}; 229 $self->{_activity} = AnyEvent->now;
189 $self->on_error (delete $self->{on_error}) if $self->{on_error}; 230 $self->_timeout;
231
190 $self->on_drain (delete $self->{on_drain}) if $self->{on_drain}; 232 $self->on_drain (delete $self->{on_drain}) if $self->{on_drain};
191 $self->on_read (delete $self->{on_read} ) if $self->{on_read}; 233 $self->on_read (delete $self->{on_read} ) if $self->{on_read};
192 234
193 $self->start_read;
194
195 $self 235 $self
196} 236}
197 237
198sub _shutdown { 238sub _shutdown {
199 my ($self) = @_; 239 my ($self) = @_;
200 240
241 delete $self->{_tw};
201 delete $self->{rw}; 242 delete $self->{_rw};
202 delete $self->{ww}; 243 delete $self->{_ww};
203 delete $self->{fh}; 244 delete $self->{fh};
204}
205 245
246 $self->stoptls;
247}
248
206sub error { 249sub _error {
207 my ($self) = @_; 250 my ($self, $errno, $fatal) = @_;
208 251
209 {
210 local $!;
211 $self->_shutdown; 252 $self->_shutdown
212 } 253 if $fatal;
254
255 $! = $errno;
213 256
214 if ($self->{on_error}) { 257 if ($self->{on_error}) {
215 $self->{on_error}($self); 258 $self->{on_error}($self, $fatal);
216 } else { 259 } else {
217 Carp::croak "AnyEvent::Handle uncaught fatal error: $!"; 260 Carp::croak "AnyEvent::Handle uncaught error: $!";
218 } 261 }
219} 262}
220 263
221=item $fh = $handle->fh 264=item $fh = $handle->fh
222 265
223This method returns the file handle of the L<AnyEvent::Handle> object. 266This method returns the file handle of the L<AnyEvent::Handle> object.
224 267
225=cut 268=cut
226 269
227sub fh { $_[0]->{fh} } 270sub fh { $_[0]{fh} }
228 271
229=item $handle->on_error ($cb) 272=item $handle->on_error ($cb)
230 273
231Replace the current C<on_error> callback (see the C<on_error> constructor argument). 274Replace the current C<on_error> callback (see the C<on_error> constructor argument).
232 275
… …
242 285
243=cut 286=cut
244 287
245sub on_eof { 288sub on_eof {
246 $_[0]{on_eof} = $_[1]; 289 $_[0]{on_eof} = $_[1];
290}
291
292=item $handle->on_timeout ($cb)
293
294Replace the current C<on_timeout> callback, or disables the callback
295(but not the timeout) if C<$cb> = C<undef>. See C<timeout> constructor
296argument.
297
298=cut
299
300sub on_timeout {
301 $_[0]{on_timeout} = $_[1];
302}
303
304#############################################################################
305
306=item $handle->timeout ($seconds)
307
308Configures (or disables) the inactivity timeout.
309
310=cut
311
312sub timeout {
313 my ($self, $timeout) = @_;
314
315 $self->{timeout} = $timeout;
316 $self->_timeout;
317}
318
319# reset the timeout watcher, as neccessary
320# also check for time-outs
321sub _timeout {
322 my ($self) = @_;
323
324 if ($self->{timeout}) {
325 my $NOW = AnyEvent->now;
326
327 # when would the timeout trigger?
328 my $after = $self->{_activity} + $self->{timeout} - $NOW;
329
330 # now or in the past already?
331 if ($after <= 0) {
332 $self->{_activity} = $NOW;
333
334 if ($self->{on_timeout}) {
335 $self->{on_timeout}($self);
336 } else {
337 $self->_error (&Errno::ETIMEDOUT);
338 }
339
340 # callback could have changed timeout value, optimise
341 return unless $self->{timeout};
342
343 # calculate new after
344 $after = $self->{timeout};
345 }
346
347 Scalar::Util::weaken $self;
348 return unless $self; # ->error could have destroyed $self
349
350 $self->{_tw} ||= AnyEvent->timer (after => $after, cb => sub {
351 delete $self->{_tw};
352 $self->_timeout;
353 });
354 } else {
355 delete $self->{_tw};
356 }
247} 357}
248 358
249############################################################################# 359#############################################################################
250 360
251=back 361=back
… …
288=cut 398=cut
289 399
290sub _drain_wbuf { 400sub _drain_wbuf {
291 my ($self) = @_; 401 my ($self) = @_;
292 402
293 if (!$self->{ww} && length $self->{wbuf}) { 403 if (!$self->{_ww} && length $self->{wbuf}) {
294 404
295 Scalar::Util::weaken $self; 405 Scalar::Util::weaken $self;
296 406
297 my $cb = sub { 407 my $cb = sub {
298 my $len = syswrite $self->{fh}, $self->{wbuf}; 408 my $len = syswrite $self->{fh}, $self->{wbuf};
299 409
300 if ($len >= 0) { 410 if ($len >= 0) {
301 substr $self->{wbuf}, 0, $len, ""; 411 substr $self->{wbuf}, 0, $len, "";
412
413 $self->{_activity} = AnyEvent->now;
302 414
303 $self->{on_drain}($self) 415 $self->{on_drain}($self)
304 if $self->{low_water_mark} >= length $self->{wbuf} 416 if $self->{low_water_mark} >= length $self->{wbuf}
305 && $self->{on_drain}; 417 && $self->{on_drain};
306 418
307 delete $self->{ww} unless length $self->{wbuf}; 419 delete $self->{_ww} unless length $self->{wbuf};
308 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAWOULDBLOCK) { 420 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {
309 $self->error; 421 $self->_error ($!, 1);
310 } 422 }
311 }; 423 };
312 424
313 # try to write data immediately 425 # try to write data immediately
314 $cb->(); 426 $cb->();
315 427
316 # if still data left in wbuf, we need to poll 428 # if still data left in wbuf, we need to poll
317 $self->{ww} = AnyEvent->io (fh => $self->{fh}, poll => "w", cb => $cb) 429 $self->{_ww} = AnyEvent->io (fh => $self->{fh}, poll => "w", cb => $cb)
318 if length $self->{wbuf}; 430 if length $self->{wbuf};
319 }; 431 };
320} 432}
321 433
322our %WH; 434our %WH;
… …
334 @_ = ($WH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_write") 446 @_ = ($WH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_write")
335 ->($self, @_); 447 ->($self, @_);
336 } 448 }
337 449
338 if ($self->{filter_w}) { 450 if ($self->{filter_w}) {
339 $self->{filter_w}->($self, \$_[0]); 451 $self->{filter_w}($self, \$_[0]);
340 } else { 452 } else {
341 $self->{wbuf} .= $_[0]; 453 $self->{wbuf} .= $_[0];
342 $self->_drain_wbuf; 454 $self->_drain_wbuf;
343 } 455 }
344} 456}
345 457
346=item $handle->push_write (type => @args) 458=item $handle->push_write (type => @args)
347 459
348=item $handle->unshift_write (type => @args)
349
350Instead of formatting your data yourself, you can also let this module do 460Instead of formatting your data yourself, you can also let this module do
351the job by specifying a type and type-specific arguments. 461the job by specifying a type and type-specific arguments.
352 462
353Predefined types are (if you have ideas for additional types, feel free to 463Predefined types are (if you have ideas for additional types, feel free to
354drop by and tell us): 464drop by and tell us):
… …
358=item netstring => $string 468=item netstring => $string
359 469
360Formats the given value as netstring 470Formats the given value as netstring
361(http://cr.yp.to/proto/netstrings.txt, this is not a recommendation to use them). 471(http://cr.yp.to/proto/netstrings.txt, this is not a recommendation to use them).
362 472
363=back
364
365=cut 473=cut
366 474
367register_write_type netstring => sub { 475register_write_type netstring => sub {
368 my ($self, $string) = @_; 476 my ($self, $string) = @_;
369 477
370 sprintf "%d:%s,", (length $string), $string 478 sprintf "%d:%s,", (length $string), $string
371}; 479};
372 480
481=item json => $array_or_hashref
482
483Encodes the given hash or array reference into a JSON object. Unless you
484provide your own JSON object, this means it will be encoded to JSON text
485in UTF-8.
486
487JSON objects (and arrays) are self-delimiting, so you can write JSON at
488one end of a handle and read them at the other end without using any
489additional framing.
490
491The generated JSON text is guaranteed not to contain any newlines: While
492this module doesn't need delimiters after or between JSON texts to be
493able to read them, many other languages depend on that.
494
495A simple RPC protocol that interoperates easily with others is to send
496JSON arrays (or objects, although arrays are usually the better choice as
497they mimic how function argument passing works) and a newline after each
498JSON text:
499
500 $handle->push_write (json => ["method", "arg1", "arg2"]); # whatever
501 $handle->push_write ("\012");
502
503An AnyEvent::Handle receiver would simply use the C<json> read type and
504rely on the fact that the newline will be skipped as leading whitespace:
505
506 $handle->push_read (json => sub { my $array = $_[1]; ... });
507
508Other languages could read single lines terminated by a newline and pass
509this line into their JSON decoder of choice.
510
511=cut
512
513register_write_type json => sub {
514 my ($self, $ref) = @_;
515
516 require JSON;
517
518 $self->{json} ? $self->{json}->encode ($ref)
519 : JSON::encode_json ($ref)
520};
521
522=back
523
373=item AnyEvent::Handle::register_write_type type => $coderef->($self, @args) 524=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args)
374 525
375This function (not method) lets you add your own types to C<push_write>. 526This function (not method) lets you add your own types to C<push_write>.
376Whenever the given C<type> is used, C<push_write> will invoke the code 527Whenever the given C<type> is used, C<push_write> will invoke the code
377reference with the handle object and the remaining arguments. 528reference with the handle object and the remaining arguments.
378 529
… …
414the specified number of bytes which give an XML datagram. 565the specified number of bytes which give an XML datagram.
415 566
416 # in the default state, expect some header bytes 567 # in the default state, expect some header bytes
417 $handle->on_read (sub { 568 $handle->on_read (sub {
418 # some data is here, now queue the length-header-read (4 octets) 569 # some data is here, now queue the length-header-read (4 octets)
419 shift->unshift_read_chunk (4, sub { 570 shift->unshift_read (chunk => 4, sub {
420 # header arrived, decode 571 # header arrived, decode
421 my $len = unpack "N", $_[1]; 572 my $len = unpack "N", $_[1];
422 573
423 # now read the payload 574 # now read the payload
424 shift->unshift_read_chunk ($len, sub { 575 shift->unshift_read (chunk => $len, sub {
425 my $xml = $_[1]; 576 my $xml = $_[1];
426 # handle xml 577 # handle xml
427 }); 578 });
428 }); 579 });
429 }); 580 });
… …
436 587
437 # request one 588 # request one
438 $handle->push_write ("request 1\015\012"); 589 $handle->push_write ("request 1\015\012");
439 590
440 # we expect "ERROR" or "OK" as response, so push a line read 591 # we expect "ERROR" or "OK" as response, so push a line read
441 $handle->push_read_line (sub { 592 $handle->push_read (line => sub {
442 # if we got an "OK", we have to _prepend_ another line, 593 # if we got an "OK", we have to _prepend_ another line,
443 # so it will be read before the second request reads its 64 bytes 594 # so it will be read before the second request reads its 64 bytes
444 # which are already in the queue when this callback is called 595 # which are already in the queue when this callback is called
445 # we don't do this in case we got an error 596 # we don't do this in case we got an error
446 if ($_[1] eq "OK") { 597 if ($_[1] eq "OK") {
447 $_[0]->unshift_read_line (sub { 598 $_[0]->unshift_read (line => sub {
448 my $response = $_[1]; 599 my $response = $_[1];
449 ... 600 ...
450 }); 601 });
451 } 602 }
452 }); 603 });
453 604
454 # request two 605 # request two
455 $handle->push_write ("request 2\015\012"); 606 $handle->push_write ("request 2\015\012");
456 607
457 # simply read 64 bytes, always 608 # simply read 64 bytes, always
458 $handle->push_read_chunk (64, sub { 609 $handle->push_read (chunk => 64, sub {
459 my $response = $_[1]; 610 my $response = $_[1];
460 ... 611 ...
461 }); 612 });
462 613
463=over 4 614=over 4
464 615
465=cut 616=cut
466 617
467sub _drain_rbuf { 618sub _drain_rbuf {
468 my ($self) = @_; 619 my ($self) = @_;
620
621 local $self->{_in_drain} = 1;
469 622
470 if ( 623 if (
471 defined $self->{rbuf_max} 624 defined $self->{rbuf_max}
472 && $self->{rbuf_max} < length $self->{rbuf} 625 && $self->{rbuf_max} < length $self->{rbuf}
473 ) { 626 ) {
474 $! = &Errno::ENOSPC; return $self->error; 627 return $self->_error (&Errno::ENOSPC, 1);
475 } 628 }
476 629
477 return if $self->{in_drain}; 630 while () {
478 local $self->{in_drain} = 1;
479
480 while (my $len = length $self->{rbuf}) {
481 no strict 'refs'; 631 no strict 'refs';
632
633 my $len = length $self->{rbuf};
634
482 if (my $cb = shift @{ $self->{queue} }) { 635 if (my $cb = shift @{ $self->{_queue} }) {
483 unless ($cb->($self)) { 636 unless ($cb->($self)) {
484 if ($self->{eof}) { 637 if ($self->{_eof}) {
485 # no progress can be made (not enough data and no data forthcoming) 638 # no progress can be made (not enough data and no data forthcoming)
486 $! = &Errno::EPIPE; return $self->error; 639 return $self->_error (&Errno::EPIPE, 1);
487 } 640 }
488 641
489 unshift @{ $self->{queue} }, $cb; 642 unshift @{ $self->{_queue} }, $cb;
490 return; 643 last;
491 } 644 }
492 } elsif ($self->{on_read}) { 645 } elsif ($self->{on_read}) {
493 $self->{on_read}($self); 646 $self->{on_read}($self);
494 647
495 if ( 648 if (
496 $self->{eof} # if no further data will arrive
497 && $len == length $self->{rbuf} # and no data has been consumed 649 $len == length $self->{rbuf} # if no data has been consumed
498 && !@{ $self->{queue} } # and the queue is still empty 650 && !@{ $self->{_queue} } # and the queue is still empty
499 && $self->{on_read} # and we still want to read data 651 && $self->{on_read} # but we still have on_read
500 ) { 652 ) {
653 # no further data will arrive
501 # then no progress can be made 654 # so no progress can be made
502 $! = &Errno::EPIPE; return $self->error; 655 return $self->_error (&Errno::EPIPE, 1)
656 if $self->{_eof};
657
658 last; # more data might arrive
503 } 659 }
504 } else { 660 } else {
505 # read side becomes idle 661 # read side becomes idle
506 delete $self->{rw}; 662 delete $self->{_rw};
507 return; 663 last;
508 } 664 }
509 } 665 }
510 666
511 if ($self->{eof}) {
512 $self->_shutdown;
513 $self->{on_eof}($self) 667 $self->{on_eof}($self)
514 if $self->{on_eof}; 668 if $self->{_eof} && $self->{on_eof};
669
670 # may need to restart read watcher
671 unless ($self->{_rw}) {
672 $self->start_read
673 if $self->{on_read} || @{ $self->{_queue} };
515 } 674 }
516} 675}
517 676
518=item $handle->on_read ($cb) 677=item $handle->on_read ($cb)
519 678
… …
525 684
526sub on_read { 685sub on_read {
527 my ($self, $cb) = @_; 686 my ($self, $cb) = @_;
528 687
529 $self->{on_read} = $cb; 688 $self->{on_read} = $cb;
689 $self->_drain_rbuf if $cb && !$self->{_in_drain};
530} 690}
531 691
532=item $handle->rbuf 692=item $handle->rbuf
533 693
534Returns the read buffer (as a modifiable lvalue). 694Returns the read buffer (as a modifiable lvalue).
… …
582 742
583 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_read") 743 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_read")
584 ->($self, $cb, @_); 744 ->($self, $cb, @_);
585 } 745 }
586 746
587 push @{ $self->{queue} }, $cb; 747 push @{ $self->{_queue} }, $cb;
588 $self->_drain_rbuf; 748 $self->_drain_rbuf unless $self->{_in_drain};
589} 749}
590 750
591sub unshift_read { 751sub unshift_read {
592 my $self = shift; 752 my $self = shift;
593 my $cb = pop; 753 my $cb = pop;
… …
598 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::unshift_read") 758 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::unshift_read")
599 ->($self, $cb, @_); 759 ->($self, $cb, @_);
600 } 760 }
601 761
602 762
603 unshift @{ $self->{queue} }, $cb; 763 unshift @{ $self->{_queue} }, $cb;
604 $self->_drain_rbuf; 764 $self->_drain_rbuf unless $self->{_in_drain};
605} 765}
606 766
607=item $handle->push_read (type => @args, $cb) 767=item $handle->push_read (type => @args, $cb)
608 768
609=item $handle->unshift_read (type => @args, $cb) 769=item $handle->unshift_read (type => @args, $cb)
… …
615Predefined types are (if you have ideas for additional types, feel free to 775Predefined types are (if you have ideas for additional types, feel free to
616drop by and tell us): 776drop by and tell us):
617 777
618=over 4 778=over 4
619 779
620=item chunk => $octets, $cb->($self, $data) 780=item chunk => $octets, $cb->($handle, $data)
621 781
622Invoke the callback only once C<$octets> bytes have been read. Pass the 782Invoke the callback only once C<$octets> bytes have been read. Pass the
623data read to the callback. The callback will never be called with less 783data read to the callback. The callback will never be called with less
624data. 784data.
625 785
… …
648 808
649sub unshift_read_chunk { 809sub unshift_read_chunk {
650 $_[0]->unshift_read (chunk => $_[1], $_[2]); 810 $_[0]->unshift_read (chunk => $_[1], $_[2]);
651} 811}
652 812
653=item line => [$eol, ]$cb->($self, $line, $eol) 813=item line => [$eol, ]$cb->($handle, $line, $eol)
654 814
655The callback will be called only once a full line (including the end of 815The callback will be called only once a full line (including the end of
656line marker, C<$eol>) has been read. This line (excluding the end of line 816line marker, C<$eol>) has been read. This line (excluding the end of line
657marker) will be passed to the callback as second argument (C<$line>), and 817marker) will be passed to the callback as second argument (C<$line>), and
658the end of line marker as the third argument (C<$eol>). 818the end of line marker as the third argument (C<$eol>).
… …
695sub unshift_read_line { 855sub unshift_read_line {
696 my $self = shift; 856 my $self = shift;
697 $self->unshift_read (line => @_); 857 $self->unshift_read (line => @_);
698} 858}
699 859
700=item netstring => $cb->($string) 860=item netstring => $cb->($handle, $string)
701 861
702A netstring (http://cr.yp.to/proto/netstrings.txt, this is not an endorsement). 862A netstring (http://cr.yp.to/proto/netstrings.txt, this is not an endorsement).
703 863
704Throws an error with C<$!> set to EBADMSG on format violations. 864Throws an error with C<$!> set to EBADMSG on format violations.
705 865
… …
709 my ($self, $cb) = @_; 869 my ($self, $cb) = @_;
710 870
711 sub { 871 sub {
712 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) { 872 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) {
713 if ($_[0]{rbuf} =~ /[^0-9]/) { 873 if ($_[0]{rbuf} =~ /[^0-9]/) {
714 $! = &Errno::EBADMSG; 874 $self->_error (&Errno::EBADMSG);
715 $self->error;
716 } 875 }
717 return; 876 return;
718 } 877 }
719 878
720 my $len = $1; 879 my $len = $1;
… …
723 my $string = $_[1]; 882 my $string = $_[1];
724 $_[0]->unshift_read (chunk => 1, sub { 883 $_[0]->unshift_read (chunk => 1, sub {
725 if ($_[1] eq ",") { 884 if ($_[1] eq ",") {
726 $cb->($_[0], $string); 885 $cb->($_[0], $string);
727 } else { 886 } else {
728 $! = &Errno::EBADMSG; 887 $self->_error (&Errno::EBADMSG);
729 $self->error;
730 } 888 }
731 }); 889 });
732 }); 890 });
733 891
734 1 892 1
735 } 893 }
736}; 894};
737 895
738=item regex => $accept[, $reject[, $skip], $cb->($data) 896=item regex => $accept[, $reject[, $skip], $cb->($handle, $data)
739 897
740Makes a regex match against the regex object C<$accept> and returns 898Makes a regex match against the regex object C<$accept> and returns
741everything up to and including the match. 899everything up to and including the match.
742 900
743Example: read a single line terminated by '\n'. 901Example: read a single line terminated by '\n'.
… …
791 return 1; 949 return 1;
792 } 950 }
793 951
794 # reject 952 # reject
795 if ($reject && $$rbuf =~ $reject) { 953 if ($reject && $$rbuf =~ $reject) {
796 $! = &Errno::EBADMSG; 954 $self->_error (&Errno::EBADMSG);
797 $self->error;
798 } 955 }
799 956
800 # skip 957 # skip
801 if ($skip && $$rbuf =~ $skip) { 958 if ($skip && $$rbuf =~ $skip) {
802 $data .= substr $$rbuf, 0, $+[0], ""; 959 $data .= substr $$rbuf, 0, $+[0], "";
… …
804 961
805 () 962 ()
806 } 963 }
807}; 964};
808 965
966=item json => $cb->($handle, $hash_or_arrayref)
967
968Reads a JSON object or array, decodes it and passes it to the callback.
969
970If a C<json> object was passed to the constructor, then that will be used
971for the final decode, otherwise it will create a JSON coder expecting UTF-8.
972
973This read type uses the incremental parser available with JSON version
9742.09 (and JSON::XS version 2.2) and above. You have to provide a
975dependency on your own: this module will load the JSON module, but
976AnyEvent does not depend on it itself.
977
978Since JSON texts are fully self-delimiting, the C<json> read and write
979types are an ideal simple RPC protocol: just exchange JSON datagrams. See
980the C<json> write type description, above, for an actual example.
981
982=cut
983
984register_read_type json => sub {
985 my ($self, $cb, $accept, $reject, $skip) = @_;
986
987 require JSON;
988
989 my $data;
990 my $rbuf = \$self->{rbuf};
991
992 my $json = $self->{json} ||= JSON->new->utf8;
993
994 sub {
995 my $ref = $json->incr_parse ($self->{rbuf});
996
997 if ($ref) {
998 $self->{rbuf} = $json->incr_text;
999 $json->incr_text = "";
1000 $cb->($self, $ref);
1001
1002 1
1003 } else {
1004 $self->{rbuf} = "";
1005 ()
1006 }
1007 }
1008};
1009
809=back 1010=back
810 1011
811=item AnyEvent::Handle::register_read_type type => $coderef->($self, $cb, @args) 1012=item AnyEvent::Handle::register_read_type type => $coderef->($handle, $cb, @args)
812 1013
813This function (not method) lets you add your own types to C<push_read>. 1014This function (not method) lets you add your own types to C<push_read>.
814 1015
815Whenever the given C<type> is used, C<push_read> will invoke the code 1016Whenever the given C<type> is used, C<push_read> will invoke the code
816reference with the handle object, the callback and the remaining 1017reference with the handle object, the callback and the remaining
… …
818 1019
819The code reference is supposed to return a callback (usually a closure) 1020The code reference is supposed to return a callback (usually a closure)
820that works as a plain read callback (see C<< ->push_read ($cb) >>). 1021that works as a plain read callback (see C<< ->push_read ($cb) >>).
821 1022
822It should invoke the passed callback when it is done reading (remember to 1023It should invoke the passed callback when it is done reading (remember to
823pass C<$self> as first argument as all other callbacks do that). 1024pass C<$handle> as first argument as all other callbacks do that).
824 1025
825Note that this is a function, and all types registered this way will be 1026Note that this is a function, and all types registered this way will be
826global, so try to use unique names. 1027global, so try to use unique names.
827 1028
828For examples, see the source of this module (F<perldoc -m AnyEvent::Handle>, 1029For examples, see the source of this module (F<perldoc -m AnyEvent::Handle>,
… …
831=item $handle->stop_read 1032=item $handle->stop_read
832 1033
833=item $handle->start_read 1034=item $handle->start_read
834 1035
835In rare cases you actually do not want to read anything from the 1036In rare cases you actually do not want to read anything from the
836socket. In this case you can call C<stop_read>. Neither C<on_read> no 1037socket. In this case you can call C<stop_read>. Neither C<on_read> nor
837any queued callbacks will be executed then. To start reading again, call 1038any queued callbacks will be executed then. To start reading again, call
838C<start_read>. 1039C<start_read>.
839 1040
1041Note that AnyEvent::Handle will automatically C<start_read> for you when
1042you change the C<on_read> callback or push/unshift a read callback, and it
1043will automatically C<stop_read> for you when neither C<on_read> is set nor
1044there are any read requests in the queue.
1045
840=cut 1046=cut
841 1047
842sub stop_read { 1048sub stop_read {
843 my ($self) = @_; 1049 my ($self) = @_;
844 1050
845 delete $self->{rw}; 1051 delete $self->{_rw};
846} 1052}
847 1053
848sub start_read { 1054sub start_read {
849 my ($self) = @_; 1055 my ($self) = @_;
850 1056
851 unless ($self->{rw} || $self->{eof}) { 1057 unless ($self->{_rw} || $self->{_eof}) {
852 Scalar::Util::weaken $self; 1058 Scalar::Util::weaken $self;
853 1059
854 $self->{rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub { 1060 $self->{_rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub {
855 my $rbuf = $self->{filter_r} ? \my $buf : \$self->{rbuf}; 1061 my $rbuf = $self->{filter_r} ? \my $buf : \$self->{rbuf};
856 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf; 1062 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf;
857 1063
858 if ($len > 0) { 1064 if ($len > 0) {
1065 $self->{_activity} = AnyEvent->now;
1066
859 $self->{filter_r} 1067 $self->{filter_r}
860 ? $self->{filter_r}->($self, $rbuf) 1068 ? $self->{filter_r}($self, $rbuf)
861 : $self->_drain_rbuf; 1069 : $self->{_in_drain} || $self->_drain_rbuf;
862 1070
863 } elsif (defined $len) { 1071 } elsif (defined $len) {
864 delete $self->{rw}; 1072 delete $self->{_rw};
865 $self->{eof} = 1; 1073 $self->{_eof} = 1;
866 $self->_drain_rbuf; 1074 $self->_drain_rbuf unless $self->{_in_drain};
867 1075
868 } elsif ($! != EAGAIN && $! != EINTR && $! != &AnyEvent::Util::WSAWOULDBLOCK) { 1076 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {
869 return $self->error; 1077 return $self->_error ($!, 1);
870 } 1078 }
871 }); 1079 });
872 } 1080 }
873} 1081}
874 1082
875sub _dotls { 1083sub _dotls {
876 my ($self) = @_; 1084 my ($self) = @_;
877 1085
1086 my $buf;
1087
878 if (length $self->{tls_wbuf}) { 1088 if (length $self->{_tls_wbuf}) {
879 while ((my $len = Net::SSLeay::write ($self->{tls}, $self->{tls_wbuf})) > 0) { 1089 while ((my $len = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) {
880 substr $self->{tls_wbuf}, 0, $len, ""; 1090 substr $self->{_tls_wbuf}, 0, $len, "";
881 } 1091 }
882 } 1092 }
883 1093
884 if (defined (my $buf = Net::SSLeay::BIO_read ($self->{tls_wbio}))) { 1094 if (length ($buf = Net::SSLeay::BIO_read ($self->{_wbio}))) {
885 $self->{wbuf} .= $buf; 1095 $self->{wbuf} .= $buf;
886 $self->_drain_wbuf; 1096 $self->_drain_wbuf;
887 } 1097 }
888 1098
889 while (defined (my $buf = Net::SSLeay::read ($self->{tls}))) { 1099 while (defined ($buf = Net::SSLeay::read ($self->{tls}))) {
1100 if (length $buf) {
890 $self->{rbuf} .= $buf; 1101 $self->{rbuf} .= $buf;
891 $self->_drain_rbuf; 1102 $self->_drain_rbuf unless $self->{_in_drain};
1103 } else {
1104 # let's treat SSL-eof as we treat normal EOF
1105 $self->{_eof} = 1;
1106 $self->_shutdown;
1107 return;
1108 }
892 } 1109 }
893 1110
894 my $err = Net::SSLeay::get_error ($self->{tls}, -1); 1111 my $err = Net::SSLeay::get_error ($self->{tls}, -1);
895 1112
896 if ($err!= Net::SSLeay::ERROR_WANT_READ ()) { 1113 if ($err!= Net::SSLeay::ERROR_WANT_READ ()) {
897 if ($err == Net::SSLeay::ERROR_SYSCALL ()) { 1114 if ($err == Net::SSLeay::ERROR_SYSCALL ()) {
898 $self->error; 1115 return $self->_error ($!, 1);
899 } elsif ($err == Net::SSLeay::ERROR_SSL ()) { 1116 } elsif ($err == Net::SSLeay::ERROR_SSL ()) {
900 $! = &Errno::EIO; 1117 return $self->_error (&Errno::EIO, 1);
901 $self->error;
902 } 1118 }
903 1119
904 # all others are fine for our purposes 1120 # all others are fine for our purposes
905 } 1121 }
906} 1122}
… …
915C<"connect">, C<"accept"> or an existing Net::SSLeay object). 1131C<"connect">, C<"accept"> or an existing Net::SSLeay object).
916 1132
917The second argument is the optional C<Net::SSLeay::CTX> object that is 1133The second argument is the optional C<Net::SSLeay::CTX> object that is
918used when AnyEvent::Handle has to create its own TLS connection object. 1134used when AnyEvent::Handle has to create its own TLS connection object.
919 1135
920=cut 1136The TLS connection object will end up in C<< $handle->{tls} >> after this
1137call and can be used or changed to your liking. Note that the handshake
1138might have already started when this function returns.
921 1139
922# TODO: maybe document... 1140=cut
1141
923sub starttls { 1142sub starttls {
924 my ($self, $ssl, $ctx) = @_; 1143 my ($self, $ssl, $ctx) = @_;
925 1144
926 $self->stoptls; 1145 $self->stoptls;
927 1146
… …
942 # http://www.mail-archive.com/openssl-dev@openssl.org/msg22420.html 1161 # http://www.mail-archive.com/openssl-dev@openssl.org/msg22420.html
943 Net::SSLeay::CTX_set_mode ($self->{tls}, 1162 Net::SSLeay::CTX_set_mode ($self->{tls},
944 (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1) 1163 (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1)
945 | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2)); 1164 | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2));
946 1165
947 $self->{tls_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1166 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
948 $self->{tls_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1167 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
949 1168
950 Net::SSLeay::set_bio ($ssl, $self->{tls_rbio}, $self->{tls_wbio}); 1169 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio});
951 1170
952 $self->{filter_w} = sub { 1171 $self->{filter_w} = sub {
953 $_[0]{tls_wbuf} .= ${$_[1]}; 1172 $_[0]{_tls_wbuf} .= ${$_[1]};
954 &_dotls; 1173 &_dotls;
955 }; 1174 };
956 $self->{filter_r} = sub { 1175 $self->{filter_r} = sub {
957 Net::SSLeay::BIO_write ($_[0]{tls_rbio}, ${$_[1]}); 1176 Net::SSLeay::BIO_write ($_[0]{_rbio}, ${$_[1]});
958 &_dotls; 1177 &_dotls;
959 }; 1178 };
960} 1179}
961 1180
962=item $handle->stoptls 1181=item $handle->stoptls
… …
968 1187
969sub stoptls { 1188sub stoptls {
970 my ($self) = @_; 1189 my ($self) = @_;
971 1190
972 Net::SSLeay::free (delete $self->{tls}) if $self->{tls}; 1191 Net::SSLeay::free (delete $self->{tls}) if $self->{tls};
1192
973 delete $self->{tls_rbio}; 1193 delete $self->{_rbio};
974 delete $self->{tls_wbio}; 1194 delete $self->{_wbio};
975 delete $self->{tls_wbuf}; 1195 delete $self->{_tls_wbuf};
976 delete $self->{filter_r}; 1196 delete $self->{filter_r};
977 delete $self->{filter_w}; 1197 delete $self->{filter_w};
978} 1198}
979 1199
980sub DESTROY { 1200sub DESTROY {
… …
1018 } 1238 }
1019} 1239}
1020 1240
1021=back 1241=back
1022 1242
1243=head1 SUBCLASSING AnyEvent::Handle
1244
1245In many cases, you might want to subclass AnyEvent::Handle.
1246
1247To make this easier, a given version of AnyEvent::Handle uses these
1248conventions:
1249
1250=over 4
1251
1252=item * all constructor arguments become object members.
1253
1254At least initially, when you pass a C<tls>-argument to the constructor it
1255will end up in C<< $handle->{tls} >>. Those members might be changes or
1256mutated later on (for example C<tls> will hold the TLS connection object).
1257
1258=item * other object member names are prefixed with an C<_>.
1259
1260All object members not explicitly documented (internal use) are prefixed
1261with an underscore character, so the remaining non-C<_>-namespace is free
1262for use for subclasses.
1263
1264=item * all members not documented here and not prefixed with an underscore
1265are free to use in subclasses.
1266
1267Of course, new versions of AnyEvent::Handle may introduce more "public"
1268member variables, but thats just life, at least it is documented.
1269
1270=back
1271
1023=head1 AUTHOR 1272=head1 AUTHOR
1024 1273
1025Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>. 1274Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>.
1026 1275
1027=cut 1276=cut

Diff Legend

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