NAME Dancer::Plugin::StreamData - stream responses that are of indeterminate (but potentially long) length SYNOPSIS package MyWebApp; use Dancer; use Dancer::Plugin::StreamData; get '/some_route' => sub { # ... return stream_data($data_obj, \&stream_my_data); }; sub stream_my_data { my ($data_obj, $writer) = @_; while ( $output = $data_obj->get_some_data() ) { $writer->write($output); } $writer->close(); } DESCRIPTION This plugin is useful for situations in which a Dancer application wants to return a large set of data, of indeterminate length, such as the results from a database query. This is especially important where the result set might total tens or hundreds of megabytes, which would be awkward to marshall within the memory of a single server process and could lead to a long delay before the start of data delivery. The "stream_data" function allows the application to stream a response one chunk at a time. For example, the data could be fetched row by row from a database server, with each row processed and then dispatched to the client via the write() method. This module can be used with any PSGI compatible web server that supports streaming. USAGE stream_data This function takes two parameters: a data object, and a stream callback. The data object need not contain the data itself; it may be a database handle or other reference by means of which the data will be obtained. The callback can be specified either as a code reference, or as a string. In the latter case, it will be invoked as a method call on the data object. Before calling "stream_data", the HTTP status and response headers may be set by the usual mechanisms of Dancer. A call to "stream_data" will terminate route processing, analagous to "send_file". Any further code in the route will be ignored. If an 'after' hook is defined in this app, it will be called as usual after route processing and may modify the response status and/or headers. The callback is invoked after the response headers have been sent. Its job is to stream the body of the response. The callback is passed two parameters: the data object, and a 'writer' object. The writer object, as specified by PSGI, implements two methods: write Sends its argument immediately to the client as part of the response body. You can call this method as many times as necessary to send all of the data. close Closes the connection to the client, terminating the response. It is important to call "close" at the end of processing, otherwise the client will erroneously report that the connection was closed prematurely before all of the data was sent. server_supports_streaming This function returns true if the server you are working with supports PSGI-style streaming, false otherwise. if ( server_supports_streaming ) { stream_data($query, 'streamResult'); } else { return $query->generateResult(); } AUTHOR Michael McClennen, SEE ALSO Dancer PSGI COPYRIGHT AND LICENSE Copyright (C) 2012 by Michael McClennen This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License. See http://dev.perl.org/licenses/ for more information.