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.62 by root, Fri Jun 6 10:49:20 2008 UTC vs.
Revision 1.79 by root, Sun Jul 27 08:37:56 2008 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 qw(WSAEWOULDBLOCK); 7use AnyEvent::Util qw(WSAEWOULDBLOCK);
8use Scalar::Util (); 8use Scalar::Util ();
9use Carp (); 9use Carp ();
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 = 4.14; 19our $VERSION = 4.22;
20 20
21=head1 SYNOPSIS 21=head1 SYNOPSIS
22 22
23 use AnyEvent; 23 use AnyEvent;
24 use AnyEvent::Handle; 24 use AnyEvent::Handle;
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->($handle) 78=item on_eof => $cb->($handle)
79 79
80Set the callback to be called when an end-of-file condition is detcted, 80Set the callback to be called when an end-of-file condition is detected,
81i.e. in the case of a socket, when the other side has closed the 81i.e. in the case of a socket, when the other side has closed the
82connection cleanly. 82connection cleanly.
83 83
84While not mandatory, it is highly recommended to set an eof callback, 84While not mandatory, it is highly recommended to set an eof callback,
85otherwise 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
124This sets the callback that is called when the write buffer becomes empty 124This sets the callback that is called when the write buffer becomes empty
125(or when the callback is set and the buffer is empty already). 125(or when the callback is set and the buffer is empty already).
126 126
127To append to the write buffer, use the C<< ->push_write >> method. 127To append to the write buffer, use the C<< ->push_write >> method.
128 128
129This callback is useful when you don't want to put all of your write data
130into the queue at once, for example, when you want to write the contents
131of some file to the socket you might not want to read the whole file into
132memory and push it into the queue, but instead only read more data from
133the file when the write queue becomes empty.
134
129=item timeout => $fractional_seconds 135=item timeout => $fractional_seconds
130 136
131If non-zero, then this enables an "inactivity" timeout: whenever this many 137If non-zero, then this enables an "inactivity" timeout: whenever this many
132seconds pass without a successful read or write on the underlying file 138seconds pass without a successful read or write on the underlying file
133handle, the C<on_timeout> callback will be invoked (and if that one is 139handle, the C<on_timeout> callback will be invoked (and if that one is
156be configured to accept only so-and-so much data that it cannot act on 162be configured to accept only so-and-so much data that it cannot act on
157(for example, when expecting a line, an attacker could send an unlimited 163(for example, when expecting a line, an attacker could send an unlimited
158amount of data without a callback ever being called as long as the line 164amount of data without a callback ever being called as long as the line
159isn't finished). 165isn't finished).
160 166
167=item autocork => <boolean>
168
169When disabled (the default), then C<push_write> will try to immediately
170write the data to the handle if possible. This avoids having to register
171a write watcher and wait for the next event loop iteration, but can be
172inefficient if you write multiple small chunks (this disadvantage is
173usually avoided by your kernel's nagle algorithm, see C<low_delay>).
174
175When enabled, then writes will always be queued till the next event loop
176iteration. This is efficient when you do many small writes per iteration,
177but less efficient when you do a single write only.
178
179=item no_delay => <boolean>
180
181When doing small writes on sockets, your operating system kernel might
182wait a bit for more data before actually sending it out. This is called
183the Nagle algorithm, and usually it is beneficial.
184
185In some situations you want as low a delay as possible, which cna be
186accomplishd by setting this option to true.
187
188The default is your opertaing system's default behaviour, this option
189explicitly enables or disables it, if possible.
190
161=item read_size => <bytes> 191=item read_size => <bytes>
162 192
163The default read block size (the amount of bytes this module will try to read 193The default read block size (the amount of bytes this module will try to read
164during each (loop iteration). Default: C<8192>. 194during each (loop iteration). Default: C<8192>.
165 195
195You can also provide your own TLS connection object, but you have 225You can also provide your own TLS connection object, but you have
196to make sure that you call either C<Net::SSLeay::set_connect_state> 226to make sure that you call either C<Net::SSLeay::set_connect_state>
197or C<Net::SSLeay::set_accept_state> on it before you pass it to 227or C<Net::SSLeay::set_accept_state> on it before you pass it to
198AnyEvent::Handle. 228AnyEvent::Handle.
199 229
200See the C<starttls> method if you need to start TLs negotiation later. 230See the C<starttls> method if you need to start TLS negotiation later.
201 231
202=item tls_ctx => $ssl_ctx 232=item tls_ctx => $ssl_ctx
203 233
204Use the given Net::SSLeay::CTX object to create the new TLS connection 234Use the given Net::SSLeay::CTX object to create the new TLS connection
205(unless a connection object was specified directly). If this parameter is 235(unless a connection object was specified directly). If this parameter is
240 } 270 }
241 271
242 $self->{_activity} = AnyEvent->now; 272 $self->{_activity} = AnyEvent->now;
243 $self->_timeout; 273 $self->_timeout;
244 274
245 $self->on_drain (delete $self->{on_drain}) if $self->{on_drain}; 275 $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain};
276 $self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay};
277
278 $self->start_read
279 if $self->{on_read};
246 280
247 $self 281 $self
248} 282}
249 283
250sub _shutdown { 284sub _shutdown {
309 343
310=cut 344=cut
311 345
312sub on_timeout { 346sub on_timeout {
313 $_[0]{on_timeout} = $_[1]; 347 $_[0]{on_timeout} = $_[1];
348}
349
350=item $handle->autocork ($boolean)
351
352Enables or disables the current autocork behaviour (see C<autocork>
353constructor argument).
354
355=cut
356
357=item $handle->no_delay ($boolean)
358
359Enables or disables the C<no_delay> setting (see constructor argument of
360the same name for details).
361
362=cut
363
364sub no_delay {
365 $_[0]{no_delay} = $_[1];
366
367 eval {
368 local $SIG{__DIE__};
369 setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1];
370 };
314} 371}
315 372
316############################################################################# 373#############################################################################
317 374
318=item $handle->timeout ($seconds) 375=item $handle->timeout ($seconds)
433 $self->_error ($!, 1); 490 $self->_error ($!, 1);
434 } 491 }
435 }; 492 };
436 493
437 # try to write data immediately 494 # try to write data immediately
438 $cb->(); 495 $cb->() unless $self->{autocork};
439 496
440 # if still data left in wbuf, we need to poll 497 # if still data left in wbuf, we need to poll
441 $self->{_ww} = AnyEvent->io (fh => $self->{fh}, poll => "w", cb => $cb) 498 $self->{_ww} = AnyEvent->io (fh => $self->{fh}, poll => "w", cb => $cb)
442 if length $self->{wbuf}; 499 if length $self->{wbuf};
443 }; 500 };
500=cut 557=cut
501 558
502register_write_type packstring => sub { 559register_write_type packstring => sub {
503 my ($self, $format, $string) = @_; 560 my ($self, $format, $string) = @_;
504 561
505 pack "$format/a", $string 562 pack "$format/a*", $string
506}; 563};
507 564
508=item json => $array_or_hashref 565=item json => $array_or_hashref
509 566
510Encodes the given hash or array reference into a JSON object. Unless you 567Encodes the given hash or array reference into a JSON object. Unless you
544 601
545 $self->{json} ? $self->{json}->encode ($ref) 602 $self->{json} ? $self->{json}->encode ($ref)
546 : JSON::encode_json ($ref) 603 : JSON::encode_json ($ref)
547}; 604};
548 605
606=item storable => $reference
607
608Freezes the given reference using L<Storable> and writes it to the
609handle. Uses the C<nfreeze> format.
610
611=cut
612
613register_write_type storable => sub {
614 my ($self, $ref) = @_;
615
616 require Storable;
617
618 pack "w/a*", Storable::nfreeze ($ref)
619};
620
549=back 621=back
550 622
551=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args) 623=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args)
552 624
553This function (not method) lets you add your own types to C<push_write>. 625This function (not method) lets you add your own types to C<push_write>.
575ways, the "simple" way, using only C<on_read> and the "complex" way, using 647ways, the "simple" way, using only C<on_read> and the "complex" way, using
576a queue. 648a queue.
577 649
578In the simple case, you just install an C<on_read> callback and whenever 650In the simple case, you just install an C<on_read> callback and whenever
579new data arrives, it will be called. You can then remove some data (if 651new data arrives, it will be called. You can then remove some data (if
580enough is there) from the read buffer (C<< $handle->rbuf >>) if you want 652enough is there) from the read buffer (C<< $handle->rbuf >>). Or you cna
581or not. 653leave the data there if you want to accumulate more (e.g. when only a
654partial message has been received so far).
582 655
583In the more complex case, you want to queue multiple callbacks. In this 656In the more complex case, you want to queue multiple callbacks. In this
584case, AnyEvent::Handle will call the first queued callback each time new 657case, AnyEvent::Handle will call the first queued callback each time new
585data arrives (also the first time it is queued) and removes it when it has 658data arrives (also the first time it is queued) and removes it when it has
586done its job (see C<push_read>, below). 659done its job (see C<push_read>, below).
604 # handle xml 677 # handle xml
605 }); 678 });
606 }); 679 });
607 }); 680 });
608 681
609Example 2: Implement a client for a protocol that replies either with 682Example 2: Implement a client for a protocol that replies either with "OK"
610"OK" and another line or "ERROR" for one request, and 64 bytes for the 683and another line or "ERROR" for the first request that is sent, and 64
611second request. Due tot he availability of a full queue, we can just 684bytes for the second request. Due to the availability of a queue, we can
612pipeline sending both requests and manipulate the queue as necessary in 685just pipeline sending both requests and manipulate the queue as necessary
613the callbacks: 686in the callbacks.
614 687
615 # request one 688When the first callback is called and sees an "OK" response, it will
689C<unshift> another line-read. This line-read will be queued I<before> the
69064-byte chunk callback.
691
692 # request one, returns either "OK + extra line" or "ERROR"
616 $handle->push_write ("request 1\015\012"); 693 $handle->push_write ("request 1\015\012");
617 694
618 # we expect "ERROR" or "OK" as response, so push a line read 695 # we expect "ERROR" or "OK" as response, so push a line read
619 $handle->push_read (line => sub { 696 $handle->push_read (line => sub {
620 # if we got an "OK", we have to _prepend_ another line, 697 # if we got an "OK", we have to _prepend_ another line,
627 ... 704 ...
628 }); 705 });
629 } 706 }
630 }); 707 });
631 708
632 # request two 709 # request two, simply returns 64 octets
633 $handle->push_write ("request 2\015\012"); 710 $handle->push_write ("request 2\015\012");
634 711
635 # simply read 64 bytes, always 712 # simply read 64 bytes, always
636 $handle->push_read (chunk => 64, sub { 713 $handle->push_read (chunk => 64, sub {
637 my $response = $_[1]; 714 my $response = $_[1];
653 ) { 730 ) {
654 return $self->_error (&Errno::ENOSPC, 1); 731 return $self->_error (&Errno::ENOSPC, 1);
655 } 732 }
656 733
657 while () { 734 while () {
658 no strict 'refs';
659
660 my $len = length $self->{rbuf}; 735 my $len = length $self->{rbuf};
661 736
662 if (my $cb = shift @{ $self->{_queue} }) { 737 if (my $cb = shift @{ $self->{_queue} }) {
663 unless ($cb->($self)) { 738 unless ($cb->($self)) {
664 if ($self->{_eof}) { 739 if ($self->{_eof}) {
828 $cb->($_[0], substr $_[0]{rbuf}, 0, $len, ""); 903 $cb->($_[0], substr $_[0]{rbuf}, 0, $len, "");
829 1 904 1
830 } 905 }
831}; 906};
832 907
833# compatibility with older API
834sub push_read_chunk {
835 $_[0]->push_read (chunk => $_[1], $_[2]);
836}
837
838sub unshift_read_chunk {
839 $_[0]->unshift_read (chunk => $_[1], $_[2]);
840}
841
842=item line => [$eol, ]$cb->($handle, $line, $eol) 908=item line => [$eol, ]$cb->($handle, $line, $eol)
843 909
844The callback will be called only once a full line (including the end of 910The callback will be called only once a full line (including the end of
845line marker, C<$eol>) has been read. This line (excluding the end of line 911line marker, C<$eol>) has been read. This line (excluding the end of line
846marker) will be passed to the callback as second argument (C<$line>), and 912marker) will be passed to the callback as second argument (C<$line>), and
861=cut 927=cut
862 928
863register_read_type line => sub { 929register_read_type line => sub {
864 my ($self, $cb, $eol) = @_; 930 my ($self, $cb, $eol) = @_;
865 931
866 $eol = qr|(\015?\012)| if @_ < 3; 932 if (@_ < 3) {
933 # this is more than twice as fast as the generic code below
934 sub {
935 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return;
936
937 $cb->($_[0], $1, $2);
938 1
939 }
940 } else {
867 $eol = quotemeta $eol unless ref $eol; 941 $eol = quotemeta $eol unless ref $eol;
868 $eol = qr|^(.*?)($eol)|s; 942 $eol = qr|^(.*?)($eol)|s;
869 943
870 sub { 944 sub {
871 $_[0]{rbuf} =~ s/$eol// or return; 945 $_[0]{rbuf} =~ s/$eol// or return;
872 946
873 $cb->($_[0], $1, $2); 947 $cb->($_[0], $1, $2);
948 1
874 1 949 }
875 } 950 }
876}; 951};
877
878# compatibility with older API
879sub push_read_line {
880 my $self = shift;
881 $self->push_read (line => @_);
882}
883
884sub unshift_read_line {
885 my $self = shift;
886 $self->unshift_read (line => @_);
887}
888 952
889=item regex => $accept[, $reject[, $skip], $cb->($handle, $data) 953=item regex => $accept[, $reject[, $skip], $cb->($handle, $data)
890 954
891Makes a regex match against the regex object C<$accept> and returns 955Makes a regex match against the regex object C<$accept> and returns
892everything up to and including the match. 956everything up to and including the match.
1013register_read_type packstring => sub { 1077register_read_type packstring => sub {
1014 my ($self, $cb, $format) = @_; 1078 my ($self, $cb, $format) = @_;
1015 1079
1016 sub { 1080 sub {
1017 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method 1081 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method
1018 defined (my $len = eval { unpack $format, $_[0]->{rbuf} }) 1082 defined (my $len = eval { unpack $format, $_[0]{rbuf} })
1019 or return; 1083 or return;
1020 1084
1085 $format = length pack $format, $len;
1086
1087 # bypass unshift if we already have the remaining chunk
1088 if ($format + $len <= length $_[0]{rbuf}) {
1089 my $data = substr $_[0]{rbuf}, $format, $len;
1090 substr $_[0]{rbuf}, 0, $format + $len, "";
1091 $cb->($_[0], $data);
1092 } else {
1021 # remove prefix 1093 # remove prefix
1022 substr $_[0]->{rbuf}, 0, (length pack $format, $len), ""; 1094 substr $_[0]{rbuf}, 0, $format, "";
1023 1095
1024 # read rest 1096 # read remaining chunk
1025 $_[0]->unshift_read (chunk => $len, $cb); 1097 $_[0]->unshift_read (chunk => $len, $cb);
1098 }
1026 1099
1027 1 1100 1
1028 } 1101 }
1029}; 1102};
1030 1103
1045the C<json> write type description, above, for an actual example. 1118the C<json> write type description, above, for an actual example.
1046 1119
1047=cut 1120=cut
1048 1121
1049register_read_type json => sub { 1122register_read_type json => sub {
1050 my ($self, $cb, $accept, $reject, $skip) = @_; 1123 my ($self, $cb) = @_;
1051 1124
1052 require JSON; 1125 require JSON;
1053 1126
1054 my $data; 1127 my $data;
1055 my $rbuf = \$self->{rbuf}; 1128 my $rbuf = \$self->{rbuf};
1067 1 1140 1
1068 } else { 1141 } else {
1069 $self->{rbuf} = ""; 1142 $self->{rbuf} = "";
1070 () 1143 ()
1071 } 1144 }
1145 }
1146};
1147
1148=item storable => $cb->($handle, $ref)
1149
1150Deserialises a L<Storable> frozen representation as written by the
1151C<storable> write type (BER-encoded length prefix followed by nfreeze'd
1152data).
1153
1154Raises C<EBADMSG> error if the data could not be decoded.
1155
1156=cut
1157
1158register_read_type storable => sub {
1159 my ($self, $cb) = @_;
1160
1161 require Storable;
1162
1163 sub {
1164 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method
1165 defined (my $len = eval { unpack "w", $_[0]{rbuf} })
1166 or return;
1167
1168 my $format = length pack "w", $len;
1169
1170 # bypass unshift if we already have the remaining chunk
1171 if ($format + $len <= length $_[0]{rbuf}) {
1172 my $data = substr $_[0]{rbuf}, $format, $len;
1173 substr $_[0]{rbuf}, 0, $format + $len, "";
1174 $cb->($_[0], Storable::thaw ($data));
1175 } else {
1176 # remove prefix
1177 substr $_[0]{rbuf}, 0, $format, "";
1178
1179 # read remaining chunk
1180 $_[0]->unshift_read (chunk => $len, sub {
1181 if (my $ref = eval { Storable::thaw ($_[1]) }) {
1182 $cb->($_[0], $ref);
1183 } else {
1184 $self->_error (&Errno::EBADMSG);
1185 }
1186 });
1187 }
1188
1189 1
1072 } 1190 }
1073}; 1191};
1074 1192
1075=back 1193=back
1076 1194
1337=over 4 1455=over 4
1338 1456
1339=item * all constructor arguments become object members. 1457=item * all constructor arguments become object members.
1340 1458
1341At least initially, when you pass a C<tls>-argument to the constructor it 1459At least initially, when you pass a C<tls>-argument to the constructor it
1342will end up in C<< $handle->{tls} >>. Those members might be changes or 1460will end up in C<< $handle->{tls} >>. Those members might be changed or
1343mutated later on (for example C<tls> will hold the TLS connection object). 1461mutated later on (for example C<tls> will hold the TLS connection object).
1344 1462
1345=item * other object member names are prefixed with an C<_>. 1463=item * other object member names are prefixed with an C<_>.
1346 1464
1347All object members not explicitly documented (internal use) are prefixed 1465All object members not explicitly documented (internal use) are prefixed

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines