--- AnyEvent/lib/AnyEvent/Handle.pm	2008/06/06 15:33:10	1.67
+++ AnyEvent/lib/AnyEvent/Handle.pm	2008/07/27 08:37:56	1.79
@@ -1,7 +1,7 @@
 package AnyEvent::Handle;
 
 no warnings;
-use strict;
+use strict qw(subs vars);
 
 use AnyEvent ();
 use AnyEvent::Util qw(WSAEWOULDBLOCK);
@@ -16,7 +16,7 @@
 
 =cut
 
-our $VERSION = 4.15;
+our $VERSION = 4.22;
 
 =head1 SYNOPSIS
 
@@ -77,7 +77,7 @@
 
 =item on_eof => $cb->($handle)
 
-Set the callback to be called when an end-of-file condition is detcted,
+Set the callback to be called when an end-of-file condition is detected,
 i.e. in the case of a socket, when the other side has closed the
 connection cleanly.
 
@@ -126,6 +126,12 @@
 
 To append to the write buffer, use the C<< ->push_write >> method.
 
+This callback is useful when you don't want to put all of your write data
+into the queue at once, for example, when you want to write the contents
+of some file to the socket you might not want to read the whole file into
+memory and push it into the queue, but instead only read more data from
+the file when the write queue becomes empty.
+
 =item timeout => $fractional_seconds
 
 If non-zero, then this enables an "inactivity" timeout: whenever this many
@@ -158,6 +164,30 @@
 amount of data without a callback ever being called as long as the line
 isn't finished).
 
+=item autocork => <boolean>
+
+When disabled (the default), then C<push_write> will try to immediately
+write the data to the handle if possible. This avoids having to register
+a write watcher and wait for the next event loop iteration, but can be
+inefficient if you write multiple small chunks (this disadvantage is
+usually avoided by your kernel's nagle algorithm, see C<low_delay>).
+
+When enabled, then writes will always be queued till the next event loop
+iteration. This is efficient when you do many small writes per iteration,
+but less efficient when you do a single write only.
+
+=item no_delay => <boolean>
+
+When doing small writes on sockets, your operating system kernel might
+wait a bit for more data before actually sending it out. This is called
+the Nagle algorithm, and usually it is beneficial.
+
+In some situations you want as low a delay as possible, which cna be
+accomplishd by setting this option to true.
+
+The default is your opertaing system's default behaviour, this option
+explicitly enables or disables it, if possible.
+
 =item read_size => <bytes>
 
 The default read block size (the amount of bytes this module will try to read
@@ -197,7 +227,7 @@
 or C<Net::SSLeay::set_accept_state> on it before you pass it to
 AnyEvent::Handle.
 
-See the C<starttls> method if you need to start TLs negotiation later.
+See the C<starttls> method if you need to start TLS negotiation later.
 
 =item tls_ctx => $ssl_ctx
 
@@ -242,7 +272,8 @@
    $self->{_activity} = AnyEvent->now;
    $self->_timeout;
 
-   $self->on_drain (delete $self->{on_drain}) if $self->{on_drain};
+   $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain};
+   $self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay};
 
    $self->start_read
       if $self->{on_read};
@@ -316,6 +347,29 @@
    $_[0]{on_timeout} = $_[1];
 }
 
+=item $handle->autocork ($boolean)
+
+Enables or disables the current autocork behaviour (see C<autocork>
+constructor argument).
+
+=cut
+
+=item $handle->no_delay ($boolean)
+
+Enables or disables the C<no_delay> setting (see constructor argument of
+the same name for details).
+
+=cut
+
+sub no_delay {
+   $_[0]{no_delay} = $_[1];
+
+   eval {
+      local $SIG{__DIE__};
+      setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1];
+   };
+}
+
 #############################################################################
 
 =item $handle->timeout ($seconds)
@@ -438,7 +492,7 @@
       };
 
       # try to write data immediately
-      $cb->();
+      $cb->() unless $self->{autocork};
 
       # if still data left in wbuf, we need to poll
       $self->{_ww} = AnyEvent->io (fh => $self->{fh}, poll => "w", cb => $cb)
@@ -595,8 +649,9 @@
 
 In the simple case, you just install an C<on_read> callback and whenever
 new data arrives, it will be called. You can then remove some data (if
-enough is there) from the read buffer (C<< $handle->rbuf >>) if you want
-or not.
+enough is there) from the read buffer (C<< $handle->rbuf >>). Or you cna
+leave the data there if you want to accumulate more (e.g. when only a
+partial message has been received so far).
 
 In the more complex case, you want to queue multiple callbacks. In this
 case, AnyEvent::Handle will call the first queued callback each time new
@@ -624,13 +679,17 @@
       });
    });
 
-Example 2: Implement a client for a protocol that replies either with
-"OK" and another line or "ERROR" for one request, and 64 bytes for the
-second request. Due tot he availability of a full queue, we can just
-pipeline sending both requests and manipulate the queue as necessary in
-the callbacks:
+Example 2: Implement a client for a protocol that replies either with "OK"
+and another line or "ERROR" for the first request that is sent, and 64
+bytes for the second request. Due to the availability of a queue, we can
+just pipeline sending both requests and manipulate the queue as necessary
+in the callbacks.
+
+When the first callback is called and sees an "OK" response, it will
+C<unshift> another line-read. This line-read will be queued I<before> the
+64-byte chunk callback.
 
-   # request one
+   # request one, returns either "OK + extra line" or "ERROR"
    $handle->push_write ("request 1\015\012");
 
    # we expect "ERROR" or "OK" as response, so push a line read
@@ -647,7 +706,7 @@
       }
    });
 
-   # request two
+   # request two, simply returns 64 octets
    $handle->push_write ("request 2\015\012");
 
    # simply read 64 bytes, always
@@ -673,8 +732,6 @@
    }
 
    while () {
-      no strict 'refs';
-
       my $len = length $self->{rbuf};
 
       if (my $cb = shift @{ $self->{_queue} }) {
@@ -848,15 +905,6 @@
    }
 };
 
-# compatibility with older API
-sub push_read_chunk {
-   $_[0]->push_read (chunk => $_[1], $_[2]);
-}
-
-sub unshift_read_chunk {
-   $_[0]->unshift_read (chunk => $_[1], $_[2]);
-}
-
 =item line => [$eol, ]$cb->($handle, $line, $eol)
 
 The callback will be called only once a full line (including the end of
@@ -881,29 +929,27 @@
 register_read_type line => sub {
    my ($self, $cb, $eol) = @_;
 
-   $eol = qr|(\015?\012)| if @_ < 3;
-   $eol = quotemeta $eol unless ref $eol;
-   $eol = qr|^(.*?)($eol)|s;
+   if (@_ < 3) {
+      # this is more than twice as fast as the generic code below
+      sub {
+         $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return;
 
-   sub {
-      $_[0]{rbuf} =~ s/$eol// or return;
+         $cb->($_[0], $1, $2);
+         1
+      }
+   } else {
+      $eol = quotemeta $eol unless ref $eol;
+      $eol = qr|^(.*?)($eol)|s;
 
-      $cb->($_[0], $1, $2);
-      1
+      sub {
+         $_[0]{rbuf} =~ s/$eol// or return;
+
+         $cb->($_[0], $1, $2);
+         1
+      }
    }
 };
 
-# compatibility with older API
-sub push_read_line {
-   my $self = shift;
-   $self->push_read (line => @_);
-}
-
-sub unshift_read_line {
-   my $self = shift;
-   $self->unshift_read (line => @_);
-}
-
 =item regex => $accept[, $reject[, $skip], $cb->($handle, $data)
 
 Makes a regex match against the regex object C<$accept> and returns
@@ -1033,14 +1079,23 @@
 
    sub {
       # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method
-      defined (my $len = eval { unpack $format, $_[0]->{rbuf} })
+      defined (my $len = eval { unpack $format, $_[0]{rbuf} })
          or return;
 
-      # remove prefix
-      substr $_[0]->{rbuf}, 0, (length pack $format, $len), "";
+      $format = length pack $format, $len;
 
-      # read rest
-      $_[0]->unshift_read (chunk => $len, $cb);
+      # bypass unshift if we already have the remaining chunk
+      if ($format + $len <= length $_[0]{rbuf}) {
+         my $data = substr $_[0]{rbuf}, $format, $len;
+         substr $_[0]{rbuf}, 0, $format + $len, "";
+         $cb->($_[0], $data);
+      } else {
+         # remove prefix
+         substr $_[0]{rbuf}, 0, $format, "";
+
+         # read remaining chunk
+         $_[0]->unshift_read (chunk => $len, $cb);
+      }
 
       1
    }
@@ -1107,20 +1162,31 @@
 
    sub {
       # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method
-      defined (my $len = eval { unpack "w", $_[0]->{rbuf} })
+      defined (my $len = eval { unpack "w", $_[0]{rbuf} })
          or return;
 
-      # remove prefix
-      substr $_[0]->{rbuf}, 0, (length pack "w", $len), "";
+      my $format = length pack "w", $len;
 
-      # read rest
-      $_[0]->unshift_read (chunk => $len, sub {
-         if (my $ref = eval { Storable::thaw ($_[1]) }) {
-            $cb->($_[0], $ref);
-         } else {
-            $self->_error (&Errno::EBADMSG);
-         }
-      });
+      # bypass unshift if we already have the remaining chunk
+      if ($format + $len <= length $_[0]{rbuf}) {
+         my $data = substr $_[0]{rbuf}, $format, $len;
+         substr $_[0]{rbuf}, 0, $format + $len, "";
+         $cb->($_[0], Storable::thaw ($data));
+      } else {
+         # remove prefix
+         substr $_[0]{rbuf}, 0, $format, "";
+
+         # read remaining chunk
+         $_[0]->unshift_read (chunk => $len, sub {
+            if (my $ref = eval { Storable::thaw ($_[1]) }) {
+               $cb->($_[0], $ref);
+            } else {
+               $self->_error (&Errno::EBADMSG);
+            }
+         });
+      }
+
+      1
    }
 };
 
@@ -1391,7 +1457,7 @@
 =item * all constructor arguments become object members.
 
 At least initially, when you pass a C<tls>-argument to the constructor it
-will end up in C<< $handle->{tls} >>. Those members might be changes or
+will end up in C<< $handle->{tls} >>. Those members might be changed or
 mutated later on (for example C<tls> will hold the TLS connection object).
 
 =item * other object member names are prefixed with an C<_>.