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.65 by root, Fri Jun 6 11:05:16 2008 UTC vs.
Revision 1.69 by root, Sun Jun 15 21:44:56 2008 UTC

… …
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.15; 19our $VERSION = 4.151;
20 20
21=head1 SYNOPSIS 21=head1 SYNOPSIS
22 22
23 use AnyEvent; 23 use AnyEvent;
24 use AnyEvent::Handle; 24 use AnyEvent::Handle;
… …
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
… …
241 247
242 $self->{_activity} = AnyEvent->now; 248 $self->{_activity} = AnyEvent->now;
243 $self->_timeout; 249 $self->_timeout;
244 250
245 $self->on_drain (delete $self->{on_drain}) if $self->{on_drain}; 251 $self->on_drain (delete $self->{on_drain}) if $self->{on_drain};
252
253 $self->start_read
254 if $self->{on_read};
246 255
247 $self 256 $self
248} 257}
249 258
250sub _shutdown { 259sub _shutdown {
… …
590ways, the "simple" way, using only C<on_read> and the "complex" way, using 599ways, the "simple" way, using only C<on_read> and the "complex" way, using
591a queue. 600a queue.
592 601
593In the simple case, you just install an C<on_read> callback and whenever 602In the simple case, you just install an C<on_read> callback and whenever
594new data arrives, it will be called. You can then remove some data (if 603new data arrives, it will be called. You can then remove some data (if
595enough is there) from the read buffer (C<< $handle->rbuf >>) if you want 604enough is there) from the read buffer (C<< $handle->rbuf >>). Or you cna
596or not. 605leave the data there if you want to accumulate more (e.g. when only a
606partial message has been received so far).
597 607
598In the more complex case, you want to queue multiple callbacks. In this 608In the more complex case, you want to queue multiple callbacks. In this
599case, AnyEvent::Handle will call the first queued callback each time new 609case, AnyEvent::Handle will call the first queued callback each time new
600data arrives (also the first time it is queued) and removes it when it has 610data arrives (also the first time it is queued) and removes it when it has
601done its job (see C<push_read>, below). 611done its job (see C<push_read>, below).
… …
619 # handle xml 629 # handle xml
620 }); 630 });
621 }); 631 });
622 }); 632 });
623 633
624Example 2: Implement a client for a protocol that replies either with 634Example 2: Implement a client for a protocol that replies either with "OK"
625"OK" and another line or "ERROR" for one request, and 64 bytes for the 635and another line or "ERROR" for the first request that is sent, and 64
626second request. Due tot he availability of a full queue, we can just 636bytes for the second request. Due to the availability of a queue, we can
627pipeline sending both requests and manipulate the queue as necessary in 637just pipeline sending both requests and manipulate the queue as necessary
628the callbacks: 638in the callbacks.
629 639
630 # request one 640When the first callback is called and sees an "OK" response, it will
641C<unshift> another line-read. This line-read will be queued I<before> the
64264-byte chunk callback.
643
644 # request one, returns either "OK + extra line" or "ERROR"
631 $handle->push_write ("request 1\015\012"); 645 $handle->push_write ("request 1\015\012");
632 646
633 # we expect "ERROR" or "OK" as response, so push a line read 647 # we expect "ERROR" or "OK" as response, so push a line read
634 $handle->push_read (line => sub { 648 $handle->push_read (line => sub {
635 # if we got an "OK", we have to _prepend_ another line, 649 # if we got an "OK", we have to _prepend_ another line,
… …
642 ... 656 ...
643 }); 657 });
644 } 658 }
645 }); 659 });
646 660
647 # request two 661 # request two, simply returns 64 octets
648 $handle->push_write ("request 2\015\012"); 662 $handle->push_write ("request 2\015\012");
649 663
650 # simply read 64 bytes, always 664 # simply read 64 bytes, always
651 $handle->push_read (chunk => 64, sub { 665 $handle->push_read (chunk => 64, sub {
652 my $response = $_[1]; 666 my $response = $_[1];

Diff Legend

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