=head1 METHODS
=head2 long_running($name, $max, $init)
Sets up the necessary state. The C identifies this request in the user's
session, so you need to chose different Cs for different operations.
C specifies the maximum progress, so if you plan to make 5 requests to
your backend until this operation is complete, set C to 5. If you don't
need it, just set it to 0.
C should be a CodeRef to trigger your operation (to initialize a timer,
some asynchronous HTTP request, etc.). It will be called with a HashRef to the
initial state that L keeps for this operation, so you
can put your AnyEvent guards in there for example.
=head2 progress($name[, $progress[, $data]])
If called with a single argument, this returns a hash describing the current
progress:
{
progress => 1,
max => 5,
data => "some data"
}
If called with a C argument, it updates the progress. You can use
any scalar here, L will just use it without making
any assumptions.
Additionally, you can pass C. While there is no difference between
C and C (both are arbitrary scalars), it makes the separation
between a linear progress (step 2 of 5) plus an additional status message
("requesting http://www.slashdot.org/") more clear.
=head2 finished($name)
Marks the operation as finished. At the next request polling the progress, null
is returned as 'progress' member of the hash and the state is cleaned up (that
means you must not poll the request after receiving a hash with
'progress':null).
When calling C, you should also undef your guard objects, if any.
=head1 INNER WORKINGS
L keeps state by generating a unique ID for every
call of C with the same C parameter and stores the ID
in the user's session under the key '_running'.
A route handler is installed for '/_progress/:name', which should be polled
(we resort to polling due to the lack of better mechanisms in Dancer/jQuery)
by the user.
=head1 AUTHOR
Michael Stapelberg, C<< >>
=head1 BUGS
Please report any bugs or feature requests to C, or through the web interface at
L. I
will be notified, and then you'll automatically be notified of progress on your
bug as I make changes.
=head1 SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Dancer::Plugin::Progress
You can also look for information at:
=over 2
=item * RT: CPAN's request tracker
L
=back
=head1 LICENSE AND COPYRIGHT
Copyright 2010 Michael Stapelberg.
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.
=cut