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.38 by root, Mon May 26 21:28:33 2008 UTC vs.
Revision 1.51 by root, Sat May 31 13:38:01 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.1;
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 on EOF.
81 81
82While not mandatory, it is highly recommended to set an eof callback, 82While not mandatory, it is highly recommended to set an eof callback,
83otherwise you might end up with a closed socket while you are still 83otherwise you might end up with a closed socket while you are still
84waiting for data. 84waiting for data.
85 85
86=item on_error => $cb->($self) 86=item on_error => $cb->($handle)
87 87
88This is the fatal error callback, that is called when, well, a fatal error 88This is the fatal error callback, that is called when, well, a fatal error
89occurs, such as not being able to resolve the hostname, failure to connect 89occurs, such as not being able to resolve the hostname, failure to connect
90or a read error. 90or a read error.
91 91
92The object will not be in a usable state when this callback has been 92The object will not be in a usable state when this callback has been
93called. 93called.
94 94
95On callback entrance, the value of C<$!> contains the operating system 95On callback entrance, the value of C<$!> contains the operating system
96error (or C<ENOSPC>, C<EPIPE> or C<EBADMSG>). 96error (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT> or C<EBADMSG>).
97 97
98The callback should throw an exception. If it returns, then 98The callback should throw an exception. If it returns, then
99AnyEvent::Handle will C<croak> for you. 99AnyEvent::Handle will C<croak> for you.
100 100
101While not mandatory, it is I<highly> recommended to set this callback, as 101While not mandatory, it is I<highly> recommended to set this callback, as
102you will not be notified of errors otherwise. The default simply calls 102you will not be notified of errors otherwise. The default simply calls
103die. 103die.
104 104
105=item on_read => $cb->($self) 105=item on_read => $cb->($handle)
106 106
107This sets the default read callback, which is called when data arrives 107This sets the default read callback, which is called when data arrives
108and no read request is in the queue. 108and no read request is in the queue.
109 109
110To access (and remove data from) the read buffer, use the C<< ->rbuf >> 110To access (and remove data from) the read buffer, use the C<< ->rbuf >>
111method or access the C<$self->{rbuf}> member directly. 111method or access the C<$handle->{rbuf}> member directly.
112 112
113When an EOF condition is detected then AnyEvent::Handle will first try to 113When an EOF condition is detected then AnyEvent::Handle will first try to
114feed all the remaining data to the queued callbacks and C<on_read> before 114feed all the remaining data to the queued callbacks and C<on_read> before
115calling the C<on_eof> callback. If no progress can be made, then a fatal 115calling the C<on_eof> callback. If no progress can be made, then a fatal
116error will be raised (with C<$!> set to C<EPIPE>). 116error will be raised (with C<$!> set to C<EPIPE>).
117 117
118=item on_drain => $cb->() 118=item on_drain => $cb->($handle)
119 119
120This sets the callback that is called when the write buffer becomes empty 120This sets the callback that is called when the write buffer becomes empty
121(or when the callback is set and the buffer is empty already). 121(or when the callback is set and the buffer is empty already).
122 122
123To append to the write buffer, use the C<< ->push_write >> method. 123To append to the write buffer, use the C<< ->push_write >> method.
124
125=item timeout => $fractional_seconds
126
127If non-zero, then this enables an "inactivity" timeout: whenever this many
128seconds pass without a successful read or write on the underlying file
129handle, the C<on_timeout> callback will be invoked (and if that one is
130missing, an C<ETIMEDOUT> error will be raised).
131
132Note that timeout processing is also active when you currently do not have
133any outstanding read or write requests: If you plan to keep the connection
134idle then you should disable the timout temporarily or ignore the timeout
135in the C<on_timeout> callback.
136
137Zero (the default) disables this timeout.
138
139=item on_timeout => $cb->($handle)
140
141Called whenever the inactivity timeout passes. If you return from this
142callback, then the timeout will be reset as if some activity had happened,
143so this condition is not fatal in any way.
124 144
125=item rbuf_max => <bytes> 145=item rbuf_max => <bytes>
126 146
127If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>) 147If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>)
128when the read buffer ever (strictly) exceeds this size. This is useful to 148when the read buffer ever (strictly) exceeds this size. This is useful to
135isn't finished). 155isn't finished).
136 156
137=item read_size => <bytes> 157=item read_size => <bytes>
138 158
139The default read block size (the amount of bytes this module will try to read 159The default read block size (the amount of bytes this module will try to read
140on each [loop iteration). Default: C<4096>. 160during each (loop iteration). Default: C<8192>.
141 161
142=item low_water_mark => <bytes> 162=item low_water_mark => <bytes>
143 163
144Sets the amount of bytes (default: C<0>) that make up an "empty" write 164Sets the amount of bytes (default: C<0>) that make up an "empty" write
145buffer: If the write reaches this size or gets even samller it is 165buffer: If the write reaches this size or gets even samller it is
168 188
169Use the given Net::SSLeay::CTX object to create the new TLS connection 189Use the given Net::SSLeay::CTX object to create the new TLS connection
170(unless a connection object was specified directly). If this parameter is 190(unless a connection object was specified directly). If this parameter is
171missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>. 191missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>.
172 192
193=item json => JSON or JSON::XS object
194
195This is the json coder object used by the C<json> read and write types.
196
197If you don't supply it, then AnyEvent::Handle will create and use a
198suitable one, which will write and expect UTF-8 encoded JSON texts.
199
200Note that you are responsible to depend on the JSON module if you want to
201use this functionality, as AnyEvent does not have a dependency itself.
202
173=item filter_r => $cb 203=item filter_r => $cb
174 204
175=item filter_w => $cb 205=item filter_w => $cb
176 206
177These exist, but are undocumented at this time. 207These exist, but are undocumented at this time.
192 if ($self->{tls}) { 222 if ($self->{tls}) {
193 require Net::SSLeay; 223 require Net::SSLeay;
194 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx}); 224 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx});
195 } 225 }
196 226
197 $self->on_eof (delete $self->{on_eof} ) if $self->{on_eof}; 227# $self->on_eof (delete $self->{on_eof} ) if $self->{on_eof}; # nop
198 $self->on_error (delete $self->{on_error}) if $self->{on_error}; 228# $self->on_error (delete $self->{on_error}) if $self->{on_error}; # nop
229# $self->on_read (delete $self->{on_read} ) if $self->{on_read}; # nop
199 $self->on_drain (delete $self->{on_drain}) if $self->{on_drain}; 230 $self->on_drain (delete $self->{on_drain}) if $self->{on_drain};
200 $self->on_read (delete $self->{on_read} ) if $self->{on_read}; 231
232 $self->{_activity} = AnyEvent->now;
233 $self->_timeout;
201 234
202 $self->start_read; 235 $self->start_read;
203 236
204 $self 237 $self
205} 238}
206 239
207sub _shutdown { 240sub _shutdown {
208 my ($self) = @_; 241 my ($self) = @_;
209 242
243 delete $self->{_tw};
210 delete $self->{_rw}; 244 delete $self->{_rw};
211 delete $self->{_ww}; 245 delete $self->{_ww};
212 delete $self->{fh}; 246 delete $self->{fh};
213} 247}
214 248
252 286
253sub on_eof { 287sub on_eof {
254 $_[0]{on_eof} = $_[1]; 288 $_[0]{on_eof} = $_[1];
255} 289}
256 290
291=item $handle->on_timeout ($cb)
292
293Replace the current C<on_timeout> callback, or disables the callback
294(but not the timeout) if C<$cb> = C<undef>. See C<timeout> constructor
295argument.
296
297=cut
298
299sub on_timeout {
300 $_[0]{on_timeout} = $_[1];
301}
302
303#############################################################################
304
305=item $handle->timeout ($seconds)
306
307Configures (or disables) the inactivity timeout.
308
309=cut
310
311sub timeout {
312 my ($self, $timeout) = @_;
313
314 $self->{timeout} = $timeout;
315 $self->_timeout;
316}
317
318# reset the timeout watcher, as neccessary
319# also check for time-outs
320sub _timeout {
321 my ($self) = @_;
322
323 if ($self->{timeout}) {
324 my $NOW = AnyEvent->now;
325
326 # when would the timeout trigger?
327 my $after = $self->{_activity} + $self->{timeout} - $NOW;
328
329 # now or in the past already?
330 if ($after <= 0) {
331 $self->{_activity} = $NOW;
332
333 if ($self->{on_timeout}) {
334 $self->{on_timeout}($self);
335 } else {
336 $! = Errno::ETIMEDOUT;
337 $self->error;
338 }
339
340 # callbakx 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
349 $self->{_tw} ||= AnyEvent->timer (after => $after, cb => sub {
350 delete $self->{_tw};
351 $self->_timeout;
352 });
353 } else {
354 delete $self->{_tw};
355 }
356}
357
257############################################################################# 358#############################################################################
258 359
259=back 360=back
260 361
261=head2 WRITE QUEUE 362=head2 WRITE QUEUE
306 my $len = syswrite $self->{fh}, $self->{wbuf}; 407 my $len = syswrite $self->{fh}, $self->{wbuf};
307 408
308 if ($len >= 0) { 409 if ($len >= 0) {
309 substr $self->{wbuf}, 0, $len, ""; 410 substr $self->{wbuf}, 0, $len, "";
310 411
412 $self->{_activity} = AnyEvent->now;
413
311 $self->{on_drain}($self) 414 $self->{on_drain}($self)
312 if $self->{low_water_mark} >= length $self->{wbuf} 415 if $self->{low_water_mark} >= length $self->{wbuf}
313 && $self->{on_drain}; 416 && $self->{on_drain};
314 417
315 delete $self->{_ww} unless length $self->{wbuf}; 418 delete $self->{_ww} unless length $self->{wbuf};
316 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAWOULDBLOCK) { 419 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {
317 $self->error; 420 $self->error;
318 } 421 }
319 }; 422 };
320 423
321 # try to write data immediately 424 # try to write data immediately
342 @_ = ($WH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_write") 445 @_ = ($WH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_write")
343 ->($self, @_); 446 ->($self, @_);
344 } 447 }
345 448
346 if ($self->{filter_w}) { 449 if ($self->{filter_w}) {
347 $self->{filter_w}->($self, \$_[0]); 450 $self->{filter_w}($self, \$_[0]);
348 } else { 451 } else {
349 $self->{wbuf} .= $_[0]; 452 $self->{wbuf} .= $_[0];
350 $self->_drain_wbuf; 453 $self->_drain_wbuf;
351 } 454 }
352} 455}
376 my ($self, $string) = @_; 479 my ($self, $string) = @_;
377 480
378 sprintf "%d:%s,", (length $string), $string 481 sprintf "%d:%s,", (length $string), $string
379}; 482};
380 483
484=item json => $array_or_hashref
485
486Encodes the given hash or array reference into a JSON object. Unless you
487provide your own JSON object, this means it will be encoded to JSON text
488in UTF-8.
489
490JSON objects (and arrays) are self-delimiting, so you can write JSON at
491one end of a handle and read them at the other end without using any
492additional framing.
493
494The generated JSON text is guaranteed not to contain any newlines: While
495this module doesn't need delimiters after or between JSON texts to be
496able to read them, many other languages depend on that.
497
498A simple RPC protocol that interoperates easily with others is to send
499JSON arrays (or objects, although arrays are usually the better choice as
500they mimic how function argument passing works) and a newline after each
501JSON text:
502
503 $handle->push_write (json => ["method", "arg1", "arg2"]); # whatever
504 $handle->push_write ("\012");
505
506An AnyEvent::Handle receiver would simply use the C<json> read type and
507rely on the fact that the newline will be skipped as leading whitespace:
508
509 $handle->push_read (json => sub { my $array = $_[1]; ... });
510
511Other languages could read single lines terminated by a newline and pass
512this line into their JSON decoder of choice.
513
514=cut
515
516register_write_type json => sub {
517 my ($self, $ref) = @_;
518
519 require JSON;
520
521 $self->{json} ? $self->{json}->encode ($ref)
522 : JSON::encode_json ($ref)
523};
524
381=item AnyEvent::Handle::register_write_type type => $coderef->($self, @args) 525=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args)
382 526
383This function (not method) lets you add your own types to C<push_write>. 527This function (not method) lets you add your own types to C<push_write>.
384Whenever the given C<type> is used, C<push_write> will invoke the code 528Whenever the given C<type> is used, C<push_write> will invoke the code
385reference with the handle object and the remaining arguments. 529reference with the handle object and the remaining arguments.
386 530
517 delete $self->{_rw}; 661 delete $self->{_rw};
518 return; 662 return;
519 } 663 }
520 } 664 }
521 665
522 if ($self->{_eof}) {
523 $self->_shutdown;
524 $self->{on_eof}($self) 666 $self->{on_eof}($self)
525 if $self->{on_eof}; 667 if $self->{_eof} && $self->{on_eof};
526 }
527} 668}
528 669
529=item $handle->on_read ($cb) 670=item $handle->on_read ($cb)
530 671
531This replaces the currently set C<on_read> callback, or clears it (when 672This replaces the currently set C<on_read> callback, or clears it (when
626Predefined types are (if you have ideas for additional types, feel free to 767Predefined types are (if you have ideas for additional types, feel free to
627drop by and tell us): 768drop by and tell us):
628 769
629=over 4 770=over 4
630 771
631=item chunk => $octets, $cb->($self, $data) 772=item chunk => $octets, $cb->($handle, $data)
632 773
633Invoke the callback only once C<$octets> bytes have been read. Pass the 774Invoke the callback only once C<$octets> bytes have been read. Pass the
634data read to the callback. The callback will never be called with less 775data read to the callback. The callback will never be called with less
635data. 776data.
636 777
659 800
660sub unshift_read_chunk { 801sub unshift_read_chunk {
661 $_[0]->unshift_read (chunk => $_[1], $_[2]); 802 $_[0]->unshift_read (chunk => $_[1], $_[2]);
662} 803}
663 804
664=item line => [$eol, ]$cb->($self, $line, $eol) 805=item line => [$eol, ]$cb->($handle, $line, $eol)
665 806
666The callback will be called only once a full line (including the end of 807The callback will be called only once a full line (including the end of
667line marker, C<$eol>) has been read. This line (excluding the end of line 808line marker, C<$eol>) has been read. This line (excluding the end of line
668marker) will be passed to the callback as second argument (C<$line>), and 809marker) will be passed to the callback as second argument (C<$line>), and
669the end of line marker as the third argument (C<$eol>). 810the end of line marker as the third argument (C<$eol>).
706sub unshift_read_line { 847sub unshift_read_line {
707 my $self = shift; 848 my $self = shift;
708 $self->unshift_read (line => @_); 849 $self->unshift_read (line => @_);
709} 850}
710 851
711=item netstring => $cb->($string) 852=item netstring => $cb->($handle, $string)
712 853
713A netstring (http://cr.yp.to/proto/netstrings.txt, this is not an endorsement). 854A netstring (http://cr.yp.to/proto/netstrings.txt, this is not an endorsement).
714 855
715Throws an error with C<$!> set to EBADMSG on format violations. 856Throws an error with C<$!> set to EBADMSG on format violations.
716 857
744 885
745 1 886 1
746 } 887 }
747}; 888};
748 889
749=item regex => $accept[, $reject[, $skip], $cb->($data) 890=item regex => $accept[, $reject[, $skip], $cb->($handle, $data)
750 891
751Makes a regex match against the regex object C<$accept> and returns 892Makes a regex match against the regex object C<$accept> and returns
752everything up to and including the match. 893everything up to and including the match.
753 894
754Example: read a single line terminated by '\n'. 895Example: read a single line terminated by '\n'.
815 956
816 () 957 ()
817 } 958 }
818}; 959};
819 960
961=item json => $cb->($handle, $hash_or_arrayref)
962
963Reads a JSON object or array, decodes it and passes it to the callback.
964
965If a C<json> object was passed to the constructor, then that will be used
966for the final decode, otherwise it will create a JSON coder expecting UTF-8.
967
968This read type uses the incremental parser available with JSON version
9692.09 (and JSON::XS version 2.2) and above. You have to provide a
970dependency on your own: this module will load the JSON module, but
971AnyEvent does not depend on it itself.
972
973Since JSON texts are fully self-delimiting, the C<json> read and write
974types are an ideal simple RPC protocol: just exchange JSON datagrams. See
975the C<json> write type description, above, for an actual example.
976
977=cut
978
979register_read_type json => sub {
980 my ($self, $cb, $accept, $reject, $skip) = @_;
981
982 require JSON;
983
984 my $data;
985 my $rbuf = \$self->{rbuf};
986
987 my $json = $self->{json} ||= JSON->new->utf8;
988
989 sub {
990 my $ref = $json->incr_parse ($self->{rbuf});
991
992 if ($ref) {
993 $self->{rbuf} = $json->incr_text;
994 $json->incr_text = "";
995 $cb->($self, $ref);
996
997 1
998 } else {
999 $self->{rbuf} = "";
1000 ()
1001 }
1002 }
1003};
1004
820=back 1005=back
821 1006
822=item AnyEvent::Handle::register_read_type type => $coderef->($self, $cb, @args) 1007=item AnyEvent::Handle::register_read_type type => $coderef->($handle, $cb, @args)
823 1008
824This function (not method) lets you add your own types to C<push_read>. 1009This function (not method) lets you add your own types to C<push_read>.
825 1010
826Whenever the given C<type> is used, C<push_read> will invoke the code 1011Whenever the given C<type> is used, C<push_read> will invoke the code
827reference with the handle object, the callback and the remaining 1012reference with the handle object, the callback and the remaining
829 1014
830The code reference is supposed to return a callback (usually a closure) 1015The code reference is supposed to return a callback (usually a closure)
831that works as a plain read callback (see C<< ->push_read ($cb) >>). 1016that works as a plain read callback (see C<< ->push_read ($cb) >>).
832 1017
833It should invoke the passed callback when it is done reading (remember to 1018It should invoke the passed callback when it is done reading (remember to
834pass C<$self> as first argument as all other callbacks do that). 1019pass C<$handle> as first argument as all other callbacks do that).
835 1020
836Note that this is a function, and all types registered this way will be 1021Note that this is a function, and all types registered this way will be
837global, so try to use unique names. 1022global, so try to use unique names.
838 1023
839For examples, see the source of this module (F<perldoc -m AnyEvent::Handle>, 1024For examples, see the source of this module (F<perldoc -m AnyEvent::Handle>,
865 $self->{_rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub { 1050 $self->{_rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub {
866 my $rbuf = $self->{filter_r} ? \my $buf : \$self->{rbuf}; 1051 my $rbuf = $self->{filter_r} ? \my $buf : \$self->{rbuf};
867 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf; 1052 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf;
868 1053
869 if ($len > 0) { 1054 if ($len > 0) {
1055 $self->{_activity} = AnyEvent->now;
1056
870 $self->{filter_r} 1057 $self->{filter_r}
871 ? $self->{filter_r}->($self, $rbuf) 1058 ? $self->{filter_r}($self, $rbuf)
872 : $self->_drain_rbuf; 1059 : $self->_drain_rbuf;
873 1060
874 } elsif (defined $len) { 1061 } elsif (defined $len) {
875 delete $self->{_rw}; 1062 delete $self->{_rw};
876 $self->{_eof} = 1; 1063 $self->{_eof} = 1;
877 $self->_drain_rbuf; 1064 $self->_drain_rbuf;
878 1065
879 } elsif ($! != EAGAIN && $! != EINTR && $! != &AnyEvent::Util::WSAWOULDBLOCK) { 1066 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {
880 return $self->error; 1067 return $self->error;
881 } 1068 }
882 }); 1069 });
883 } 1070 }
884} 1071}
932call and can be used or changed to your liking. Note that the handshake 1119call and can be used or changed to your liking. Note that the handshake
933might have already started when this function returns. 1120might have already started when this function returns.
934 1121
935=cut 1122=cut
936 1123
937# TODO: maybe document...
938sub starttls { 1124sub starttls {
939 my ($self, $ssl, $ctx) = @_; 1125 my ($self, $ssl, $ctx) = @_;
940 1126
941 $self->stoptls; 1127 $self->stoptls;
942 1128

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines