NAME

Dancer2::Plugin::ProgressStatus - Keeps track of progress status

VERSION

version 0.018

SYNOPSIS

get '/route' => sub {
  my $progress = start_progress_status({ name => 'progress1', total => 100 });
  while($some_condition) {
      # .. do some slow running stuff
      $progress++; # add's one to the progress
      $progress->add_message('an update message');
  }

  # $progress goes out of scope here and automatically ends the progress meter
};

Then with some javascript on the front end, something like this:

function checkProgress() {
    $.getJSON('/_progress_status/progress1', function(data) {
       if ( !data.in_progress ) {
          console.log("Finished progress1");
          return;
       }
       setTimeout(function() {
          checkProgress,
          3000
       });
    })
}

DESCRIPTION

Records and fetches progress entries.

This module allows your route to start a progress status meter and update it whilst your long running task is in progress. How you break up the running task is up to you.

e.g. Let's say your webapp uploads a file to the server. The server then needs to upload that file to a new location. Although the client can already get progress info about the first upload, it cannot get progress about the second upload. This plugin allows you to separately query the server about a long running job.

Whilst the long running task is in progress, an AJAX GET request can be made to /_progress_status/:name to fetch JSON serialized data representing the progress status that matches :name

WebServer Dependencies:

This progress module does not depend on an event loop based webserver such as Twiggy as the long running request and the query to fetch the progress can be issued entirely separately.

It does currently depend on: 1. More than one worker process running to enable the handling of multiple requests at the same time

2. The webserver being hosted on one machine and uses local file storage for the progress data and as such is probably not suitable for a production environment at this time.

CONFIG

plugins:
  ProgressStatus:
    dir: "/tmp/dancer_progress"

The only plugin setting currently understood is where to store the progress data. This is required. If the directory does not exist, it will be created.

SEE ALSO

Dancer2

METHODS

start_progress_status

my $prog = start_progress_status({ name => "MyProgressStatus" });

Registers a new progress status for this session and automatically creates a route for returning data about the progress status.

Returns a progress object that you can use to set the progress. e.g.

$prog++;
$prog->add_message();
$prog->increment(10);

If an existing progress status with this name already exists and is currently in progress this call will die without affecting the original status. Either wrap this in an eval, use "is_progress_running" in Dancer2::Plugin::ProgressStatus or ensure by some other means that two progress meters don't start at the same time.

The route for querying the progress status is defined as:

GET /_progress_status/:name

It returns a JSON serialized structure something like:

{
  total: 100,
  count: 20,
  messages: [ "array of messages" ],
  in_progress: true
  status: 'some status message'
}

When the progress object goes out of scope in_progress is automatically set to false.

set_progress_status takes a name (required), a total (defaults to 100) a count (defaults to 0), and messages an optional arrayref of message strings.

If name is not a sufficient identifier to determine uniqueness, the client can pass ?progress_id=$progress_id. This will automatically be appended to the progress status name without the route needing to know about it.

progress_id can be seen as the progress name defined by the client, and name as the progress name defined by the server. Either can be used, at least one must be used.

is_progress_running

my $bool = is_progress_running($name);

Returns true if there is a running progress by this name. "start_progess_status" in Dancer2::Plugin::ProgressStatus dies if two progress meters with the same name start at the same time so this can be used to confirm without catching the start call in an eval.

AUTHOR

Steven Humphrey

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Steven Humphrey.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.