/ 
Redis-JobQueue-1.19
River stage zero No dependents
/ Redis::JobQueue::Job

NAME

Redis::JobQueue::Job - Object interface for creating and manipulating jobs

VERSION

This documentation refers to Redis::JobQueue::Job version 1.19

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_modified( 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.

EXPORT

None by default.

The following additional constants, defining defaults for various parameters, are available for export:

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.

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.

progress

Optional attribute, the progress of the task, contains a user-defined value from 0 to 1.

message

Optional attribute, a string message with additional user-defined information.

created

Returns time of job creation. Set to the current time (Time::HiRes::time) when job is created.

If necessary, alternative value can be set as:

$job->created( time );

updated

Returns the time of the most recent modification of the job.

Set to the current time (Time::HiRes::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 );

started

Returns the time that the job started processing. Set to the current time (Time::HiRes::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 );

completed

Returns the time of the task completion.

It is set to 0 when task is created.

Set to Time::HiRes::time when "status" is changed to "STATUS_COMPLETED".

Can be modified manually:

$job->completed( time );

Change the completed attribute sets failed = 0. The attributes completed and failed are mutually exclusive.

failed

Returns the time of the task failure.

It is set to 0 when task is created.

Set to Time::HiRes::time when "status" is changed to "STATUS_FAILED".

Can be modified manually:

$job->failed( time );

Change the failed attribute sets completed = 0. The attributes failed and completed are mutually exclusive.

elapsed

Returns the time (a floating seconds since the epoch) 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" and must not begin with '__'}. An invalid name causes die (confess).

clear_modified( @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.

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::JobQueue::Util - String manipulation utilities.

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>

Please use GitHub project link above to report problems or contact authors.

CONTRIBUTORS

Alexander Solovey

Jeremy Jordan

Sergiy Zuban

Vlad Marchenko

COPYRIGHT AND LICENSE

Copyright (C) 2012-2016 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.