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.

These accessors allow access to information about an instantiated Helios::Job object:

debug() whether Debug Mode is enabled or not
get/setConfig() Helios configuration passed by the system to the job object
get/setArgs() hashref of the job's arguments (interpreted from the arg string)
get/setArgString() the raw XML of the job arguments

Several accessors are pass-through accessors to access values in the underlying TheSchwartz::Job object

get/setJobid() jobid of the job in the job queue
get/setFailures() number of previous failures of the job before current run
get/setJobtypeid() jobtypeid value of the job
get/setJobType() jobtype name of the job
get/setUniqkey() uniqkey value of the job (see TheSchwartz documentation)
get/setRunAfter() current run_after value of the job
get/setGrabbedUntil() current grabbed_until value of the job
get/setCoalesce() coalesce value of the job (see TheSchwartz documentation)

When running a job, your service class need not access any of these values directly, though the information is available if you need it (for example, to log how many failures your job has encountered before the current run). When submitting a job, several of the set* accessors are needed to set up the job before submission; see the section on the submit() method for more information.

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.

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.

Defers processing of a job even though it was available for processing in the queue. The job will be seen as available for processing again when the grabbed_until time has expired (the default is 60 minutes). If your service employs the job retry API, a declined job run does not count against the job's retry count.

Unlike the completed() and failed*() methods above, deferred() is actually only a wrapper around TheSchwartz 1.10's TheSchwartz::Job->declined() method for now. No job history is recorded in the HELIOS_JOB_HISTORY_TB in the collective database. This may change in the future.

So, for example, to submit a Helios::TestService to the Helios system, you need to do the following:

# you need Helios::Service and Helios::Job
use Helios::Service;
use Helios::Job;
# these are the job arguments we want to pass to Helios::TestService
my $jobxml = "<job><params><string1>This is a test</string1/params>/job>";
# first, use Helios::Service to get the Helios configuration
my $srv = Helios::Service->new();
$srv->prep();
my $config = $srv->getConfig();
# once you have the config, you can set up the Helios::Job
my $job = Helios::Job->new();
$job->setConfig($config);
$job->setJobType('Helios::TestService');
$job->setArgString($jobxml);
# then submit the job (this will throw an exception if something goes wrong)
my $jobid = $job->submit();
print "Submitted job $jobid to Helios\n";

Both Helios::Service->prep() and Helios::Job->submit() will throw exceptions if they encounter errors, so a safer example would catch them:

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).

Portions of this software, where noted, are Copyright (C) 2012 by Andrew Johnson.

Portions of this software, where noted, are Copyright (C) 2013 by Logical Helion, LLC.

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.