Sub::Slice::Manual 1.048

Sub::Slice::Manual is a Perl module with user guide for Sub::Slice.

USING Sub::Slice

Sub::Slice is a way of breaking down a long-running process and maintaining state across a stateless protocol. This allows the client to draw a progress bar or abort the process part-way through.

The mechanism used by Sub::Slice is similar to the session management used on many web user authentication systems. However rather than simply passing an ID back as a token as these systems do, in Sub::Slice a data structure with richer information is passed to the client, allowing the client to make some intelligent decisions rather than blindly maintain state.

Use of Sub::Slice is best explained with a minimal example. Assume that there is a remoting protocol between the client and server such as XML/HTTP. For the sake of brevity, assume that methods called in package Server:: on the client are magically remoted to the server.

The server does two things. The first is to issue a token for the client to use:

#Server
sub create_token {
my $job = new Sub::Slice();
return $job->token;
}
The second is to provide the routine into which the token is passed for each iteration:
sub do_work {
my $token = shift;
my $job = new Sub::Slice(token => $token);

at_start $job sub {
my $files = files_to_process();

#Store some data defining the work to do
$job->store("files", $files);
};

at_stage $job "each_iteration" sub {

#Get some work
my $files = $job->fetch("files");
my $file = shift @$files;

my $was_ok = process_file($file);

#Record we did the work
$job->store("files", $files);

#Check if theres any more work left to do
$job->done() unless(@$files);

};
}

The client somehow gets a token back from the server. It then passes this back to the server for each iteration. It can inspect the token to check if there is any more work left.

#Client
my $token = Server::create_token();
for(1 .. MAX_ITERATIONS) {
Server::do_work($token);
last if $token->{done};
}