NAME
MediaCloud::JobManager::Job - An abstract class for a "function".
LINGO
function
A function to be run by locally or remotely, e.g.
add_default_feeds.job
An instance of the function doing the actual job with specific parameters.
ABSTRACT INTERFACE
The following subroutines must be implemented by the subclasses of this class.
REQUIRED
run($self, $args)
Run the job.
Parameters:
$self, a reference to the instance of the function class(optional)
$args(hashref), arguments needed for running the function
An instance (object) of the class will be created before each run. Class instance variables (e.g. $self->_my_variable) will be discarded after each run.
Returns result on success (serializable by the JSON module). The result will be discarded if the job is added as a background process.
Provides progress reports when available:
by calling
$self->set_progress($numerator, $denominator)
die()s on error.
Writes log to STDOUT or STDERR (preferably the latter).
(static) retries()
Return the number of retries for each job.
Returns a number of retries each job will be attempted at. For example, if the number of retries is set to 3, the job will be attempted 4 four times in total.
Returns 0 if the job should not be retried (attempted only once).
Default implementation of this subroutine returns 0 (no retries).
(static) unique()
Return true if the function is "unique" (only for remote requests).
Returns true if two or more jobs with the same parameters can not be run at the same and instead should be merged into one.
Default implementation of this subroutine returns "true".
(static) configuration()
Return an instance or a subclass of MediaCloud::JobManager::Configuration to be used as default configuration by both workers and clients.
Workers and clients will still be able to override this configuration by passing their own config argument. This configuration will be used if no such argument is present.
Default implementation of this subroutine returns an instance of MediaCloud::JobManager::Configuration (default configuration).
(static) priority()
Return priority of the job ("low", "normal" or "high"). This will influence the queueing mechanism and prioritize "high priority" jobs.
Returns one of the three constants:
MJM_JOB_PRIORITY_LOW(), if the job is considered of "low priority".MJM_JOB_PRIORITY_NORMAL()if the job is considered of "normal priority".MJM_JOB_PRIORITY_HIGH()if the job is considered of "high priority".
Default implementation of this subroutine returns MJM_JOB_PRIORITY_NORMAL() ("normal priority" job).
HELPER SUBROUTINES
The following subroutines can be used by the deriving class.
$self->set_progress($numerator, $denominator)
Provide progress report while running the task (from run()).
Examples:
$self->set_progress(3, 10)3 out of 10 subtasks are complete.
$self->set_progress(45, 100)45 out of 100 subtasks are complete (or 45% complete).
CLIENT SUBROUTINES
The following subroutines can be used by clients to run a function.
(static) $class->run_locally([$args, $config])
Run locally and right away, blocking the parent process until the job is finished.
Parameters:
(optional)
$args(hashref), arguments required for running the function (serializable by the JSON module)(optional, internal) job handle to be later used by send_progress()
Returns result (may be false of undef) on success, die()s on error
(static) $class->run_remotely([$args])
Run remotely, wait for the task to complete, return the result; block the process until the job is complete.
Parameters:
(optional)
$args(hashref), arguments needed for running the function (serializable by the JSON module)
Returns result (may be false of undef) on success, die()s on error
(static) $class->add_to_queue([$args, $config])
Add to queue remotely, do not wait for the task to complete, return immediately; do not block the parent process until the job is complete.
Parameters:
(optional)
$args(hashref), arguments needed for running the function (serializable by the JSON module)
Returns job ID if the job was added to queue successfully, die()s on error.
(static) name()
Returns function's name (e.g. NinetyNineBottlesOfBeer).
Usage:
NinetyNineBottlesOfBeer->name();Parameters:
Class or class instance