NAME

Bio::CIPRES::Job - a CIPRES job class

SYNOPSIS

    use Bio::CIPRES;

    my $ua  = Bio::CIPRES->new( %args );
    my $job = $ua->submit_job( %params );

    $job->wait(6000) or die "Timeout waiting for job completion";

    warn "Job returned non-zero status" if ($job->exit_code);

    print STDOUT $job->stdout;
    print STDERR $job->stderr;

    $job->delete;

DESCRIPTION

Bio::CIPRES::Job is a class representing a single CIPRES job. Its purpose is to simplify handling of job status and job outputs.

Users should not create Bio::CIPRES::Job objects directly - they are returned by methods in the Bio::CIPRES class.

METHODS

stage

    if ($job->stage eq 'QUEUE') {}

Returns a string describing the current stage of the job.

refresh

    $job->refresh;

Makes a call to the API to retrieve the current status of the job, and updates the object attributes accordingly. Generally this is called as part of a while loop while waiting for a job to complete.

is_finished

    if ($job->is_finished) {}

Returns true if the job has completed, false otherwise.

is_failed

    die "CIPRES error" if ($job->is_failed);

Returns true if the submission has failed, false otherwise. Note that, according to the API docs, this value can be false even if the job itself has failed for some reason. Use Bio::CIPRES::Job::exit_code for a more reliable way to check for job success.

poll_interval

    my $s = $job->poll_interval;

Returns the minimum number of seconds that the client should wait between status updates. Generally this is called as part of a while loop.

wait

    $job->wait($timeout) or die "Timeout waiting for job to finish";

Enters a blocking loop waiting for the job to finish. Takes a single optional argument of the maximum number of seconds to wait before timing out (default: no timeout). Returns true if the job finishes or false if the wait times out.

outputs

    my @results = $job->outputs(
        name  => 'foo.txt',
        group => 'bar',
        force_download => 0,
    );

Returns an array of Bio::CIPRES::Output objects representing files generated by the job. Generally this should only be called after a job has completed. By default returns all available outputs. Possible arguments include:

• group

  Limit returned outputs to those in the specified group

• name

  Limit returned output to that with the specified name

• force_download

  Force the client to re-download output list (as opposed to using cached values). This is automatically called from within Bio::CIPRES::Job::refresh and generally doesn't need to be set by the user. (default: false)

exit_code

    warn "Job returned non-zero status" if ($job->exit_code != 0);

Returns the actual exit code of the job on the remote server. Exit codes < 0 indicate API or server errors, while exit codes > 0 indicate errors in the job tool itself (possibly described in the tool's documentation).

timed_out

    warn "Job timed out on remote scheduler" if ($job->timed_out);

Returns true if the job timed out according to the remote scheduler, false if it did not, and undefined if unable to be determined. Note that the method for detecting such state relies on parsing STDERR text and may be subject to false negatives. A true return value is thus relatively reliable, while a false value should not be strictly relied upon for any critical purposes.

stdout

    print STDOUT $job->stdout;

Returns the STDOUT from the job as a string.

stderr

    print STDERR $job->stderr;

Returns the STDERR from the job as a string.

submit_time

Returns the original submission date/time as a Time::Piece object

messages

Returns a reference to an array of Bio::CIPRES::Message objects associated with the job

delete

    $job->delete;

Deletes a job from the user workspace, including all of the output files. Generally this should be called once a job is completed and all desired output files have been fetched. This will help to keep the user workspace clean.

CAVEATS AND BUGS

Please reports bugs to the author.

AUTHOR

Jeremy Volkening <jdv@base2bio.com>

COPYRIGHT AND LICENSE

Copyright 2016 Jeremy Volkening

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

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. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.