NAME
Redis::JobQueue::Job - Object interface for creating and manipulating jobs
VERSION
This documentation refers to Redis::JobQueue::Job version 1.02
SYNOPSIS
There are several ways to create a Redis::JobQueue::Job object:
my $pre_job = {
id => '4BE19672-C503-11E1-BF34-28791473A258',
queue => 'lovely_queue',
job => 'strong_job',
expire => 12*60*60, # 12h
status => STATUS_CREATED,
workload => \'Some stuff up to 512MB long',
result => \'JOB result comes here, up to 512MB long',
};
my $job = Redis::JobQueue::Job->new(
id => $pre_job->{id},
queue => $pre_job->{queue},
job => $pre_job->{job},
expire => $pre_job->{expire},
status => $pre_job->{status},
workload => $pre_job->{workload},
result => $pre_job->{result},
);
$job = Redis::JobQueue::Job->new( $pre_job );
my $next_job = Redis::JobQueue::Job->new( $job );Access methods to read and assign the relevant attributes of the object. For example:
$job->$workload( \'New workload' );
# or
$job->$workload( 'New workload' );
my $id = $job->id;
# 'workload' and 'result' return a reference to the data
my $result = ${$job->result};Returns a list of names of the modified object fields:
my @modified = $job->modified_attributes;Resets the sign of changing an attribute. For example:
$job->clear_variability( qw( status ) );DESCRIPTION
Job API is implemented by Redis::JobQueue::Job class.
The main features of the Redis::JobQueue::Job class are:
Provides an object oriented model of communication.
Supports data representing various aspects of the job.
Supports the creation of the job object, an automatic allowance for the change attributes and the ability to cleanse the signs of change attributes.
CONSTRUCTOR
An error will cause the program to halt if the argument is not valid.
new( id => $uuid, ... )
It generates a Job object and can be called as either a class method or an object method.
If invoked with the first argument being an object of Redis::JobQueue::Job class or a reference to a hash, then the new object attribute values are taken from the hash of the first argument.
new optionally takes arguments. These arguments are in key-value pairs.
This example illustrates a new() call with all the valid arguments:
$job = Redis::JobQueue::Job->new(
id => '4BE19672-C503-11E1-BF34-28791473A258',
# UUID string, using conventional UUID string format.
# Do not use it because filled in automatically when
# you create a job.
queue => 'lovely_queue', # The name of the job queue.
# (required)
job => 'strong_job', # The name of the job.
# (optional attribute)
expire => 12*60*60, # Job's time to live in seconds.
# 0 for no expire time.
# (required)
status => STATUS_CREATED, # Current status of the job.
# Do not use it because value should be set by the worker.
workload => \'Some stuff up to 512MB long',
# Baseline data for the function of the worker
# (the function name specified in the 'job').
# Can be a scalar, an object or a reference to a scalar, hash, or array
result => \'JOB result comes here, up to 512MB long',
# The result of the function of the worker
# (the function name specified in the 'job').
# Do not use it because value should be set by the worker.
);Returns the object itself, we can chain settings.
The attributes workload and result may contain a large amount of data, therefore, it is desirable that they be passed as references to the actual data to improve performance.
Do not use spaces in an id attribute value.
Each element in the struct data has an accessor method, which is used to assign and fetch the element's value.
METHODS
An error will cause the program to halt if the argument is not valid.
id
queue
job
expire
status
workload
result
The family of methods for a multitude of accessor methods for your data with the appropriate names. These methods are able to read and assign the relevant attributes of the object.
As attributes workload and result may contain a large amount of data (scalars, references to arrays and hashes, objects):
A read method returns a reference to the data.
A write method can receive both data or a reference to the data.
created
Returns time (UTC) of job creation. Set to the current time (time) when job is created.
If necessary, alternative value can be set as:
$job->created( time );started
Returns the time (UTC) that the job started processing. Set to the current time (time) when the "status" of the job is set to "STATUS_WORKING".
If necessary, you can set your own value, for example:
$job->started( time );updated
Returns the time (UTC) of the most recent modification of the job.
Set to the current time (time) when value(s) of any of the following data changes: "status", "workload", "result", "progress", "message", "completed", "failed".
Can be updated manually:
$job->updated( time );completed
Returns the time (UTC) of the task completion.
It is set to 0 when task is created.
Set to time when "status" is changed to "STATUS_COMPLETED".
Can be modified manually:
$job->completed( time );failed
Returns the time (UTC) of the task failure.
It is set to 0 when task is created.
Set to time when "status" is changed to "STATUS_FAILED".
Can be modified manually:
$job->failed( time );elapsed
Returns the time (in seconds) since the job started processing (see "started") till job "completed" or "failed" or to the current time. Returns undef if the start processing time was set to 0.
meta_data
With no arguments, returns a reference to a hash of metadata (additional information related to the job). For example:
my $md = $job->meta_data;Hash value of an individual item metadata is available by specifying the name of the hash key. For example:
my $foo = $job->meta_data( 'foo' );Separate metadata value can be set as follows:
my $foo = $job->meta_data( next => 16 );Group metadata can be specified by reference to a hash. Metadata may contain scalars, references to arrays and hashes, objects. For example:
$job->meta_data( {
'foo' => 12,
'bar' => [ 13, 14, 15 ],
'other' => { a => 'b', c => 'd' },
} );The name of the metadata fields should not match the standard names returned by "job_attributes". An invalid name causes die (confess).
clear_variability( @fields )
Resets the sign of any specified attributes that have been changed. If no attribute names are specified, the signs are reset for all attributes.
modified_attributes
Returns a list of names of the object attributes that have been modified.
job_attributes
Returns a sorted list of the names of object attributes.
EXPORT
None by default.
Additional constants are available for import, which can be used to define some type of parameters.
These are the defaults:
STATUS_CREATED-
Initial status of the job, showing that it was created.
STATUS_WORKING-
Jobs is being executed. Set by the worker function.
STATUS_COMPLETED-
Job is completed. Set by the worker function.
STATUS_FAILED-
Job has failed. Set by the worker function.
User himself should specify the status " STATUS_WORKING", " STATUS_COMPLETED", " STATUS_FAILED" or own status when processing the job.
DIAGNOSTICS
An error will cause the program to halt (confess) if an argument is not valid. Use $@ for the analysis of the specific reasons.
SEE ALSO
The basic operation of the Redis::JobQueue package modules:
Redis::JobQueue - Object interface for creating and executing jobs queues, as well as monitoring the status and results of jobs.
Redis::JobQueue::Job - Object interface for creating and manipulating jobs.
Redis - Perl binding for Redis database.
SOURCE CODE
Redis::JobQueue is hosted on GitHub: https://github.com/TrackingSoft/Redis-JobQueue
AUTHOR
Sergey Gladkov, <sgladkov@trackingsoft.com>
CONTRIBUTORS
Alexander Solovey
Jeremy Jordan
Vlad Marchenko
COPYRIGHT AND LICENSE
Copyright (C) 2012-2013 by TrackingSoft LLC.
This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic at http://dev.perl.org/licenses/artistic.html.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.