Permalink
Browse files

psgi.streaming MAY -> SHOULD. Remove poll_cb from the Writer spec.

  • Loading branch information...
1 parent 9170aac commit c5aa24f2b3877e00922d1663bd1c1a0cfc032b86 @miyagawa miyagawa committed Jan 6, 2010
Showing with 37 additions and 39 deletions.
  1. +22 −27 PSGI.pod
  2. +15 −12 PSGI/FAQ.pod
View
@@ -324,11 +324,8 @@ Returns true if successful.
=head3 The Response
-Applications B<MUST> return a response as a three element array reference.
-
-B<IF> the server supports the streaming (see below), an application B<MAY>
-choose to return other type of responses such as a code reference to delay the
-response.
+Applications B<SHOULD> return a response as either a three element
+array reference, or a code reference for a delayed/streaming response.
The response array reference consists of the following elements:
@@ -427,13 +424,18 @@ B<MAY> also respect this special variable, but are not required to do so.
=head2 Delayed Response and Streaming Body
-The PSGI interface allows applications and servers to provide a callback-style
-response instead of the three-element array reference. This allows for a
-delayed response and a streaming body (server push).
+The PSGI interface allows applications and servers to provide a
+callback-style response instead of the three-element array
+reference. This allows for a delayed response and a streaming body
+(server push).
+
+This interface B<SHOULD> be implemented by PSGI servers, and
+C<psgi.streaming> environment B<MUST> be set to true in such servers.
-To enable a delayed response, an application B<SHOULD> check if the
-C<psgi.streaming> environment is true. If it is, the application B<MAY> return
-a callback as its response.
+To enable a delayed response, the application B<SHOULD> return a
+callback as its response. An application B<MAY>check if the
+C<psgi.streaming> environment is true and falls back to the direct
+response if it isn't.
This callback will be called with I<another> subroutine reference (referred to
as the I<responder> from now on) as its only argument. The I<responder>
@@ -447,14 +449,16 @@ response. This is best illustrated with an example:
return sub {
my $responder = shift;
- my $content = fetch_content_from_server();
- $responder->([ 200, $headers, [ $content ] ]);
+ fetch_content_from_server(sub {
+ my $content = shift;
+ $responder->([ 200, $headers, [ $content ] ]);
+ });
};
};
-An application B<MAY> omit the third element (the body) when calling the
-I<responder>. If the body is omitted, the I<responder> will return I<yet
-another> an object which implements C<write>, C<poll_cb> and C<close>
+An application B<MAY> omit the third element (the body) when calling
+the I<responder>. If the body is omitted, the I<responder> B<MUST>
+return I<yet another> object which implements C<write> and C<close>
methods. Again, an example illustrates this best.
my $app = sub {
@@ -476,19 +480,10 @@ methods. Again, an example illustrates this best.
};
};
-B<XXX: still need detalis on write, poll_cb, and close API methods.>
-
This delayed response and streaming API is useful if you want to
implement a non-blocking I/O based server streaming or long-poll Comet
-push technology.
-
-This interface is optional: An application B<SHOULD> check if the server
-supports streaming before attempting to use it. Servers B<MAY> throw an
-exception if they do not support streaming a response.
-
-Servers B<MUST> set C<psgi.streaming> to true if this interface is supported,
-and if it is supported, servers B<MUST> return a writer object when the third
-argument (response body) to the I<responder> is omitted.
+push technology, but could also be used to write unbuffered write in a
+blocking server.
=head2 Middleware
View
@@ -436,9 +436,7 @@ hard to do non-blocking I/O unless you use Coro.
If you want to do server push, where your application runs in an event
loop and push content body to the client as it's ready, you should
-first check if the server supports the delayed response, by looking at
-C<psgi.streaming> env hash, and then return a callback to delay the
-response.
+return a callback to delay the response.
# long-poll comet like a chat application
my $app = sub {
@@ -458,8 +456,11 @@ response.
C<wait_for_new_message> can be blocking or non-blocking: it's up to
you. Most of the case you want to run it non-blockingly and should use
-event loops like L<AnyEvent>. You're suggested to check
-C<psgi.nonblocking> value to see that it's possible.
+event loops like L<AnyEvent>. You may also check C<psgi.nonblocking>
+value to see that it's possible and fallback to a blocking call
+otherwise to be compatible with non streaming capable servers, but
+you're not required to, since it's defined as SHOULD in the
+specification now.
Also, to stream the content body (like streaming messages over the
Flash socket or multipart XMLHTTPRequest):
@@ -487,15 +488,17 @@ Flash socket or multipart XMLHTTPRequest):
We have servers that support non-blocking (where C<psgi.nonblocking>
is set to true), but the problem is that framework side doesn't
-necessary support streaming. For instance Catalyst has C<write> method
-on the response object:
+necessarily support asynchronous event loop. For instance Catalyst has
+C<write> method on the response object:
while ($cond) {
$c->res->write($some_stuff);
}
-But it obviously blocks in the application unless you run your
-application in multithread (or Coro) environments.
+This should work with all servers with C<psgi.streaming> support even
+if they are blocking, and it should be fine if they're running in
+multiple processes (C<psgi.multiprocess> is true).
+
L<Catalyst::Engine::PSGI> also supports setting an IO::Handle-like
object that supports C<getline>, so using L<IO::Handle::Util>
@@ -505,9 +508,9 @@ object that supports C<getline>, so using L<IO::Handle::Util>
$c->res->body($io);
And that works fine to do streaming, but it's blocking (I<pull>)
-rather than server push, so you should be careful not to run this
-application on non-blocking (and non-multiprocess) server
-environments.
+rather than asynchronous server push, so again you should be careful
+not to run this application on non-blocking (and non-multiprocess)
+server environments.
We expect that more web frameworks will appear that is focused on, or
existent frameworks will add support for, asynchronous and

0 comments on commit c5aa24f

Please sign in to comment.