a few more dynamic content examples

mojolicious · Mar 20, 2015 · e42600f · e42600f
1 parent cdd197a
commit e42600f
Show file tree

Hide file tree

Showing 3 changed files with 49 additions and 4 deletions.
diff --git a/Changes b/Changes
@@ -1,5 +1,5 @@
 
-6.04  2015-03-20
+6.04  2015-03-21
   - Improved Mojo::Reactor::EV and Mojo::Reactor::Poll to fail more
     consistently.
   - Fixed a few bugs in Mojo::DOM::CSS that required class, id and attribute

diff --git a/lib/Mojo/Content.pm b/lib/Mojo/Content.pm
@@ -577,19 +577,31 @@ Size of content already received from message in bytes.
 
 =head2 write
 
+  $content = $content->write;
+  $content = $content->write('');
   $content = $content->write($bytes);
   $content = $content->write($bytes => sub {...});
 
 Write dynamic content non-blocking, the optional drain callback will be invoked
-once all data has been written.
+once all data has been written. You can write an empty chunk at any time to end
+the stream.
+
+  # Start dynamic content, but do not write anything yet
+  $content->write;
 
 =head2 write_chunk
 
+  $content = $content->write_chunk;
+  $content = $content->write_chunk('');
   $content = $content->write_chunk($bytes);
   $content = $content->write_chunk($bytes => sub {...});
 
 Write dynamic content non-blocking with C<chunked> transfer encoding, the
-optional drain callback will be invoked once all data has been written.
+optional drain callback will be invoked once all data has been written. You can
+write an empty chunk at any time to end the stream.
+
+  # Start dynamic content, but do not write anything yet
+  $content->write_chunk;
 
 =head1 SEE ALSO
 

diff --git a/lib/Mojolicious/Controller.pm b/lib/Mojolicious/Controller.pm
@@ -921,13 +921,17 @@ parameters, so you have to make sure it is not excessively large, there's a
 =head2 write
 
   $c = $c->write;
+  $c = $c->write('');
   $c = $c->write($bytes);
   $c = $c->write(sub {...});
   $c = $c->write($bytes => sub {...});
 
 Write dynamic content non-blocking, the optional drain callback will be invoked
 once all data has been written.
 
+  # Start dynamic content, but do not write anything yet
+  $c->write;
+
   # Keep connection alive (with Content-Length header)
   $c->res->headers->content_length(6);
   $c->write('Hel' => sub {
@@ -944,6 +948,24 @@ once all data has been written.
     });
   });
 
+You can call L</"finish"> or write an empty chunk at any time to end the
+stream.
+
+  HTTP/1.1 200 OK
+  Connection: keep-alive
+  Date: Sat, 13 Sep 2014 16:48:29 GMT
+  Content-Length: 6
+  Server: Mojolicious (Perl)
+
+  Hello!
+
+  HTTP/1.1 200 OK
+  Connection: close
+  Date: Sat, 13 Sep 2014 16:48:29 GMT
+  Server: Mojolicious (Perl)
+
+  Hello!
+
 For Comet (long polling) you might also want to increase the inactivity timeout
 with L<Mojolicious::Plugin::DefaultHelpers/"inactivity_timeout">, which usually
 defaults to C<15> seconds.
@@ -954,13 +976,17 @@ defaults to C<15> seconds.
 =head2 write_chunk
 
   $c = $c->write_chunk;
+  $c = $c->write_chunk('');
   $c = $c->write_chunk($bytes);
   $c = $c->write_chunk(sub {...});
   $c = $c->write_chunk($bytes => sub {...});
 
 Write dynamic content non-blocking with C<chunked> transfer encoding, the
 optional drain callback will be invoked once all data has been written.
 
+  # Start dynamic content, but do not write anything yet
+  $c->write_chunk;
+
   # Make sure previous chunk has been written before continuing
   $c->write_chunk('He' => sub {
     my $c = shift;
@@ -970,7 +996,14 @@ optional drain callback will be invoked once all data has been written.
     });
   });
 
-You can call L</"finish"> at any time to end the stream.
+You can call L</"finish"> or write an empty chunk at any time to end the
+stream.
+
+  HTTP/1.1 200 OK
+  Connection: keep-alive
+  Date: Sat, 13 Sep 2014 16:48:29 GMT
+  Transfer-Encoding: chunked
+  Server: Mojolicious (Perl)
 
   2
   He