--- AnyEvent/lib/AnyEvent/Handle.pm	2008/06/06 15:35:30	1.68
+++ AnyEvent/lib/AnyEvent/Handle.pm	2008/06/25 20:29:32	1.70
@@ -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
@@ -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