add streaming section to rendering guide

mojolicious · Feb 12, 2016 · 038aa5a · 038aa5a
1 parent c33f844
commit 038aa5a
Show file tree

Hide file tree

Showing 14 changed files with 56 additions and 23 deletions.
diff --git a/lib/Mojo/Content.pm b/lib/Mojo/Content.pm
@@ -553,7 +553,7 @@ Size of content already received from message in bytes.
   $content = $content->write($bytes);
   $content = $content->write($bytes => sub {...});
 
-Write dynamic content non-blocking, the optional drain callback will be invoked
+Write dynamic content non-blocking, the optional drain callback will be executed
 once all data has been written. Calling this method without a chunk of data
 will finalize the L</"headers"> and allow for dynamic content to be written
 later. You can write an empty chunk of data at any time to end the stream.
@@ -575,7 +575,7 @@ later. You can write an empty chunk of data at any time to end the stream.
   $content = $content->write_chunk($bytes => sub {...});
 
 Write dynamic content non-blocking with chunked transfer encoding, the optional
-drain callback will be invoked once all data has been written. Calling this
+drain callback will be executed once all data has been written. Calling this
 method without a chunk of data will finalize the L</"headers"> and allow for
 dynamic content to be written later. You can write an empty chunk of data at any
 time to end the stream.

diff --git a/lib/Mojo/IOLoop.pm b/lib/Mojo/IOLoop.pm
@@ -476,7 +476,7 @@ Check if event loop is running.
   my $undef = Mojo::IOLoop->next_tick(sub {...});
   my $undef = $loop->next_tick(sub {...});
 
-Invoke callback as soon as possible, but not before returning or other
+Execute callback as soon as possible, but not before returning or other
 callbacks that have been registered with this method, always returns C<undef>.
 
   # Perform operation on next reactor tick

diff --git a/lib/Mojo/IOLoop/Stream.pm b/lib/Mojo/IOLoop/Stream.pm
@@ -304,7 +304,7 @@ stream to be inactive indefinitely.
   $stream = $stream->write($bytes);
   $stream = $stream->write($bytes => sub {...});
 
-Write data to stream, the optional drain callback will be invoked once all data
+Write data to stream, the optional drain callback will be executed once all data
 has been written.
 
 =head1 SEE ALSO

diff --git a/lib/Mojo/Reactor.pm b/lib/Mojo/Reactor.pm
@@ -105,7 +105,7 @@ L<Mojo::Reactor::Poll>.
 Watch handle for I/O events, invoking the callback whenever handle becomes
 readable or writable. Meant to be overloaded in a subclass.
 
-  # Callback will be invoked twice if handle becomes readable and writable
+  # Callback will be executed twice if handle becomes readable and writable
   $reactor->io($handle => sub {
     my ($reactor, $writable) = @_;
     say $writable ? 'Handle is writable' : 'Handle is readable';
@@ -121,7 +121,7 @@ Check if reactor is running. Meant to be overloaded in a subclass.
 
   my $undef = $reactor->next_tick(sub {...});
 
-Invoke callback as soon as possible, but not before returning or other
+Execute callback as soon as possible, but not before returning or other
 callbacks that have been registered with this method, always returns C<undef>.
 Meant to be overloaded in a subclass.
 

diff --git a/lib/Mojo/Reactor/Poll.pm b/lib/Mojo/Reactor/Poll.pm
@@ -209,7 +209,7 @@ Restart timer. Note that this method requires an active timer.
 Watch handle for I/O events, invoking the callback whenever handle becomes
 readable or writable.
 
-  # Callback will be invoked twice if handle becomes readable and writable
+  # Callback will be executed twice if handle becomes readable and writable
   $reactor->io($handle => sub {
     my ($reactor, $writable) = @_;
     say $writable ? 'Handle is writable' : 'Handle is readable';
@@ -225,7 +225,7 @@ Check if reactor is running.
 
   my $undef = $reactor->next_tick(sub {...});
 
-Invoke callback as soon as possible, but not before returning or other
+Execute callback as soon as possible, but not before returning or other
 callbacks that have been registered with this method, always returns C<undef>.
 
 =head2 one_tick

diff --git a/lib/Mojo/Transaction/WebSocket.pm b/lib/Mojo/Transaction/WebSocket.pm
@@ -494,7 +494,7 @@ Resume L</"handshake"> transaction.
   $ws = $ws->send($chars => sub {...});
 
 Send message or frame non-blocking via WebSocket, the optional drain callback
-will be invoked once all data has been written.
+will be executed once all data has been written.
 
   # Send "Ping" frame
   use Mojo::WebSocket 'WS_PING';

diff --git a/lib/Mojolicious.pm b/lib/Mojolicious.pm
@@ -303,7 +303,7 @@ controller object)
 
 =head2 around_action
 
-Emitted right before an action gets invoked and wraps around it, so you have to
+Emitted right before an action gets executed and wraps around it, so you have to
 manually forward to the next hook if you want to continue the chain. Default
 action dispatching is the last hook in the chain, yours will run before it.
 

diff --git a/lib/Mojolicious/Controller.pm b/lib/Mojolicious/Controller.pm
@@ -793,7 +793,7 @@ L<Mojolicious::Plugin::DefaultHelpers/"accepts">.
   $c = $c->send($chars => sub {...});
 
 Send message or frame non-blocking via WebSocket, the optional drain callback
-will be invoked once all data has been written. This method will automatically
+will be executed once all data has been written. This method will automatically
 respond to WebSocket handshake requests with a C<101> response status, to
 establish the WebSocket connection.
 
@@ -944,7 +944,7 @@ excessively large, there's a 16MB limit by default.
   $c = $c->write($bytes);
   $c = $c->write($bytes => sub {...});
 
-Write dynamic content non-blocking, the optional drain callback will be invoked
+Write dynamic content non-blocking, the optional drain callback will be executed
 once all data has been written. Calling this method without a chunk of data
 will finalize the response headers and allow for dynamic content to be written
 later.
@@ -969,7 +969,6 @@ You can call L</"finish"> or write an empty chunk of data 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)
@@ -998,7 +997,7 @@ defaults to C<15> seconds.
   $c = $c->write_chunk($bytes => sub {...});
 
 Write dynamic content non-blocking with chunked transfer encoding, the optional
-drain callback will be invoked once all data has been written. Calling this
+drain callback will be executed once all data has been written. Calling this
 method without a chunk of data will finalize the response headers and allow for
 dynamic content to be written later.
 
@@ -1015,7 +1014,6 @@ You can call L</"finish"> or write an empty chunk of data 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)

diff --git a/lib/Mojolicious/Guides/Cookbook.pod b/lib/Mojolicious/Guides/Cookbook.pod
@@ -1085,7 +1085,7 @@ Sending a streaming request is almost just as easy.
   # Process transaction
   $tx = $ua->start($tx);
 
-The drain callback passed to L<Mojo::Content/"write"> will be invoked whenever
+The drain callback passed to L<Mojo::Content/"write"> will be executed whenever
 the entire previous chunk of data has actually been written.
 
 =head2 Non-blocking

diff --git a/lib/Mojolicious/Guides/Growing.pod b/lib/Mojolicious/Guides/Growing.pod
@@ -385,13 +385,11 @@ L<Mojolicious::Command::get>.
   $ ./myapp.pl get -v '/?user=sebastian&pass=secr3t'
   GET /?user=sebastian&pass=secr3t HTTP/1.1
   User-Agent: Mojolicious (Perl)
-  Connection: keep-alive
   Accept-Encoding: gzip
   Content-Length: 0
   Host: localhost:59472
 
   HTTP/1.1 200 OK
-  Connection: keep-alive
   Date: Sun, 18 Jul 2010 13:09:58 GMT
   Server: Mojolicious (Perl)
   Content-Length: 12

diff --git a/lib/Mojolicious/Guides/Rendering.pod b/lib/Mojolicious/Guides/Rendering.pod
@@ -1263,6 +1263,44 @@ lot more efficient to use L<Mojolicious/"after_render">.
     <body>Compressed content.</body>
   </html>
 
+=head2 Streaming
+
+You don't have to render all content at once, the method
+L<Mojolicious::Controller/"write"> can also be used to stream a series of
+smaller chunks.
+
+  use Mojolicious::Lite;
+
+  get '/' => sub {
+    my $c = shift;
+
+    # Prepare body
+    my $body = 'Hello world!';
+    $c->res->headers->content_length(length $body);
+
+    # Start writing directly with a drain callback
+    my $drain;
+    $drain = sub {
+      my $c = shift;
+      my $chunk   = substr $body, 0, 1, '';
+      $drain      = undef unless length $body;
+      $c->write($chunk, $drain);
+    };
+    $c->$drain;
+  };
+
+  app->start;
+
+The drain callback will be executed whenever the entire previous chunk of data
+has actually been written.
+
+  HTTP/1.1 200 OK
+  Date: Sat, 13 Sep 2014 16:48:29 GMT
+  Content-Length: 12
+  Server: Mojolicious (Perl)
+
+  Hello world!
+
 =head2 Chunked transfer encoding
 
 For very dynamic content you might not know the response content length in
@@ -1288,7 +1326,6 @@ before processing continues. To end the stream you can call
 L<Mojolicious::Controller/"finish"> or write an empty chunk of data.
 
   HTTP/1.1 200 OK
-  Connection: keep-alive
   Date: Sat, 13 Sep 2014 16:48:29 GMT
   Transfer-Encoding: chunked
   Server: Mojolicious (Perl)

diff --git a/lib/Test/Mojo.pm b/lib/Test/Mojo.pm
@@ -892,7 +892,7 @@ arguments as L<Mojo::UserAgent/"options">, except for the callback.
 
   $t = $t->or(sub {...});
 
-Invoke callback if the value of L</"success"> is false.
+Execute callback if the value of L</"success"> is false.
 
   # Diagnostics
   $t->get_ok('/bad')->or(sub { diag 'Must have been Glen!' })

diff --git a/t/mojolicious/ojo.t b/t/mojolicious/ojo.t
@@ -54,10 +54,10 @@ is r([1, 2]), "[\n  1,\n  2\n]\n", 'right result';
   local *STDERR = $handle;
   my $i = 0;
   n { ++$i };
-  is $i,        1,             'block has been invoked once';
+  is $i,        1,             'block has been executed once';
   like $buffer, qr/wallclock/, 'right output';
   n { $i++ } 10;
-  is $i, 11, 'block has been invoked ten times';
+  is $i, 11, 'block has been executed ten times';
   like $buffer, qr/wallclock.*wallclock/s, 'right output';
 }
 

diff --git a/t/mojolicious/testing_app.t b/t/mojolicious/testing_app.t
@@ -16,7 +16,7 @@ my $t       = Test::Mojo->new('MojoliciousTest');
 my $success = '';
 $t->or(sub { $success .= 'one' })->success(1)->or(sub { $success .= 'two' })
   ->success(!1)->or(sub { $success .= shift->app->mode });
-is $success, 'onetesting', 'two callbacks have been invoked';
+is $success, 'onetesting', 'two callbacks have been executed';
 ok $t->get_ok('/')->success, 'test was successful';
 
 # SyntaxError::foo in testing mode (syntax error in controller)