NAME
Helios::Job - base class for jobs in the Helios job processing system
DESCRIPTION
Helios::Job is the standard representation of jobs in the Helios framework. It handles tasks related to the underlying TheSchwartz::Job objects, and provides its own methods for manipulating jobs in the Helios system.
ACCESSOR METHODS
METHODS
new($job)
ARGUMENT PROCESSING METHODS
parseArgXML($xml)
Given a string of XML, parse it into a mixed hash/arrayref structure. This uses XML::Simple.
parseArgs()
Call parseArgs() to pick the Helios job arguments (the first element of the job->args() array) from the Schwartz job object, parse the XML into a Perl data structure (via XML::Simple) and return the structure to the calling routine.
This is really a convenience method created because
$args = $self->parseArgXML( $job->arg()->[0] );looks nastier than it really needs to be.
isaMetaJob()
Returns a true value if the job is a metajob and a false value otherwise.
JOB SUCCESS/FAILURE METHODS
Use these methods to mark jobs as either successful or failed.
Helios follows the *nix concept of exitstatus: 0 is successful, nonzero is failure. If you don't specify an exitstatus when you call failed() or failedNoRetry(), 1 will be recorded as the exitstatus.
The completed(), failed(), and failedNoRetry() methods actually return the exitstatus of the job, so completed() always returns 0 and the failed methods return the exitstatus you specified (or 1 if you didn't specify one). This is to facilitate ending of service class run() methods; the caller of a run() method will cause the worker process to exit if a nonzero value is returned. If you make sure your completed() or failed()/failedNoRetry() call is the last thing you do in your run() method, everything should work fine.
completed()
Marks the job as completed successfully.
Successful jobs are marked with exitstatus of zero in Helios job history.
failed([$error][, $exitstatus])
Marks the job as failed. Allows job to be retried if the job's service class supports it. Returns the exitstatus recorded for the job (if it wasn't given, it defaults to 1).
failedNoRetry([$error][, $exitstatus])
Marks the job as permanently failed (no more retries allowed).
If not specified, exitstatus defaults to 1.
submit()
Submits a job to the Helios collective for processing. Returns the jobid if successful, throws an error if it fails.
Before a job can be successfully submitted, the following must be set first:
$job->setConfig()
$job->setArgXML()
$job->setFuncname()JOB BURSTING
Metajobs are jobs that specify multiple jobs. These metajobs will be burst apart by Helios into the constituent jobs, which will be available for processing by any of the workers of the appropriate class in the Helios collective. Metajobs provide a faster means to submit jobs in bulk to Helios; rather than submit a thousand jobs, your application can submit 1 metajob that will be burst apart by Helios into the thousand constituent jobs, which other workers will process as if they were submitted individually.
Normally, the Helios::Service base class determines whether a job is a metajob or not and can handle the bursting process without intervention from your service subclass. If you need metajobs to be burst in a way different than from the default, you may need to override Helios::Service->burstJob() in your service class (and possibly create a Helios::Job subclass with an overridden burst() method as well).
burst()
Bursts a metajob into smaller jobs. Returns the number of jobs burst if successful.
OTHER METHODS
getDriver()
Returns a Data::ObjectDriver object for use with Helios layer database updates.
SEE ALSO
Helios::Service, Helios::Error, TheSchwartz::Job, XML::Simple, Config::IniFiles
AUTHOR
Andrew Johnson, <ajohnson@ittoolbox.com>
COPYRIGHT AND LICENSE
Copyright (C) 2008 by CEB Toolbox, Inc.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.0 or, at your option, any later version of Perl 5 you may have available.
WARRANTY
This software comes with no warranty of any kind.