qb::block

Purpose

Sets job state to blocked.

 

Prototype

qb::block(ids)

 

Parameters

ids

a list of job or subjob ids.

Results

 

 

Notes

 

 

Example


use lib "$ENV{QBDIR}/api/perl";

use qb;qb::block(@ids)

qb::bottom

Purpose

Moves jobs to end of execution order queue.

 

Prototype

qb::bottom(ids)

 

Parameters

ids

a list of job or subjob ids.

Result

 

 

Comments

 

 

Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

qb::bottom(@ids)

qb::genchunks

Purpose

Generates a work agenda based on an input frame specification divided into fixed width chunks.

 

Prototype

qb::genchunks(chunksize, range)

 

Parameters

chunksize

number of frames in a single chunk

 

range

frame range format string. See qb::rangesplit() for range format.

Result

Reference to a work agenda hash.

 

Comments

 

 

Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

my $frames = qb::genchunks(5, "1-100");

qb::genframes

Purpose

Generates a work agenda based on an frame specification string.

 

Prototype

qb::genframes(range)

 

Parameters

range

Frame range format string. See qb::rangesplit() for range format.

Result

Reference to a work agenda hash.

 

Comments

 

 

Example

use lib "$ENV{QBDIR}/api/perl";

use qb;

my $frames = qb::genframes("1-100");

qb::hist

Purpose

Returns a list of history objects corresponding to the job query.

 

Prototype

qb::hist(ids)

 

Parameters

ids

Job or subjob ids.

Result

Reference to a array of hash references containing history information:
"comment": comment string
"stamp": timestamp
"jobid": job ID
"subid": subjob ID

 

Comments

 

 


Example

use lib "$ENV{QBDIR}/api/perl";

use qb;

qb::hist(@ids)

qb::hostinfo

Purpose

Returns information from list of hosts.

 

Prototype

qb::hostinfo(query)

 

Parameters

query

Hash containing host query information

Results

Array of hash references containing information about hosts meeting query:
"name": host name
"address": host IP address
"state": host state
"cluster": host cluster membership
"groups": host group membership
"stats": host statistics
"properties": Worker properties for host
"resources": Worker resources for host
"restrictions": host restrictions

 

Comments

 

 

Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

qb::hostinfo(%query)

qb::interrupt

Purpose

Forces running jobs back to pending state immediately.

 

Prototype

qb::interrupt(ids)

 

Parameters

ids

a list of job or subjob ids.

Results

 

 

 

 

 

Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

qb::interrupt(@ids)

qb::jobinfo

Purpose

Generates a list of job objects matching query filter.

 

Prototype

qb::jobinfo(query)

 

Parameters

query

Hash containing job query parameters.

Result

Reference to an array of hashes containing information regarding jobs that meet the query (all jobs if no query):
"prototype": job type
"ID": job ID
"priority": job priority
"user": job owner
"label": job label
"account": job accounting
"pid": process ID
"pgrp": process group
"cpus": cpus
"reservations": job reservations
"requirements": job requirements
"restrictions": job restrictions
"cluster": job cluster
"hosts": job hosts
"groups": host groups
"name": job name
"package": job package data hash reference
"data": job package data string
"status": current job status

 

Comments

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

qb::jobinfo(%query)

qb::joborder

Purpose

Returns a list of jobs eligible to run on specified hosts.

 

Prototype

qb::joborder(host)

 

Parameters

host

host name.

Results

Reference to an array of hashes containing job information for jobs scheduled to run on host:
"prototype": job type
"ID": job ID
"priority": job priority
"user": job owner
"label": job label
"account": job accounting
"pid": process ID
"pgrp": process group
"cpus": cpus
"reservations": job reservations
"requirements": job requirements
"restrictions": job restrictions
"cluster": job cluster
"hosts": job hosts
"groups": host groups
"name": job name
"package": job package data hash reference
"data": job package data string
"status": current job status

 

Comments

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

qb::joborder($host)

qb::kill

Purpose

Kills jobs.

 

Prototype

qb::kill(ids)

 

Parameters

ids

list of job or subjob ids.

Results

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

qb::kill(@ids)


qb::migrate

Purpose

Interrupt a running job and force to run on a different host.

 

Prototype

qb::migrate(ids)

 

Parameters

ids

a list of job or subjob ids.

Result

 

 

Comments

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

qb::migrate(@ids)

qb::modify

Purpose

modifies job parameters

 

Prototype

qb::modify(parameters, ids)

 

Parameters

parameters

Hash containing job parameters and new values.

 

ids

list of job or subjob ids to be modified

Results

 

 

Comments

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;qb::modify({ priority => 1, name => "hello world" }, 1002);

qb::preempt

Purpose

Forces running jobs back to pending state after agenda item is completed.

 

Prototype

qb::preempt(ids)

 

Parameters

ids

list of job or subjob ids.

Results

 

 

Notes

Will release host gracefully if Job Type supports an agenda.

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

qb::preempt(@ids)

qb::rangechunk

Purpose

Converts an frame range format into an array of frame ranges of a specified length.

 

Prototype

qb::rangechunk(chunksize, range)

 

Parameters

chunksize

Number of frames in a single chunk

 

range

Frame range format string. See qb::rangesplit() for range format

Result

List containing the individual frames in mode order.

 

Comments

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

qb::rangechunk($chunksize, $range)

qb::rangejoin

Purpose

Converts a list of frames into frame range format string.

 

Prototype

qb::rangejoin(frames)

 

Parameters

frames

List of frames.

Result

Frame range format string corresponding to the frame list

 

Comments

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

my $range = qb::rangejoin(1,2,3,4,5);result: $range = "1-5";

my $range = qb::rangejoin(1,3,5,7,9,11,13);

result: $range = "1-13x2";

qb::rangeorder

Purpose

Takes an input range and converts it into an array of individual numbers sorted/ordered in the method specified.

 

Prototype

qb::rangeorder(mode, range)

 

Parameters

mode

Sort order mode.Valid modes:

  1. binary,
  2. reverse
  3. rawbinary
  4. ascend
  5. descend

 

range

Frame range format string. See qb::rangesplit () for range format

Result

List containing the individual frames in mode order.

 

Comments

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;qb::rangeorder($mode, $range)

qb::rangesplit

Purpose

Takes an input range and converts it into an array of individual numbers.

 

Prototype

qb::rangesplit(range)

 

Parameters

range

Frame range format string.

Results

list of individual frame numbers

 

Comments

Range Format:
<start><end>x<step>[,<start><end>x<step>...]
Ex. 1-10x2,12,20

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

my @frame_numbers = qb::rangesplit("1-100");

result: @frame_numbers = (1,2,3,4..98,99,100);

my @frame_numbers = qb::rangesplit("1-100x10");

result: @frame_numbers = (1,11,21,31,41,51,61,71,81,91);

my @frame_numbers = qb::rangesplit("10-10");result: @frame_numbers = (-10,-9,-8,-7..6,7,8,9,10);my @frame_numbers = qb::rangesplit("-10-5");

result: @frame_numbers = (-10,-9,-8,-7,-6,-5);

my @frame_numbers = qb::rangesplit("1-5x2,10-12");

result: @frame_numbers = (1,3,5,10,11,12);

qb::remove

Purpose

Removes jobs from the Supervisor database cache.

 

Prototype

qb::remove(ids)

 

Parameters

ids

list of job or subjob ids.

Results

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;qb::remove(@ids)

qb::requeue

Purpose

Resets a failed, complete or killed job back to a initial blocked state.

 

Prototype

qb::requeue(ids)

 

Parameters

ids

a list of job or subjob ids.

Results

 

 

Comments

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;qb::requeue(@ids)


qb::resource

Purpose

Queries Supervisor for state of resources.

 

Prototype

qbresource(resources)

 

Parameters

resources

Hash describing resource keys and values

Results

 

 

Comments

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

qbresource(%resources)

qb::resume

Purpose

resumes suspended jobs.

 

Prototype

qb::resume(ids)

 

Parameters

ids

a list of job or subjob ids.

Results

 

 

Comments

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;qb::resume(ids)


qb::retry

Purpose

Resets failed, complete, or killed jobs back to the pending state.

 

Prototype

qb::retry(ids)

 

Parameters

ids

a list of job or subjob ids.

Results

 

 

Notes

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;qb::retry(@ids)

qb::stderr

Purpose

Retrieves job STDERR log file output.

 

Prototype

qb::stderr(ids)

 

Parameters

ids

list of job or subjob ids

Results

Array of hash references referring to the STDERR logs:

"data": log file contents
"jobid": job ID
"subid": subjob ID

 

Comments

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;qb::stderr(@ids)

qb::stdout

Purpose

Retrieves job STDOUT log file output.

 

Prototype

qb::stderr(ids)

 

Parameters

ids

list of job or subjob ids

Results

Array of hash references referring to the STDOUT logs.

 

Comments

Hash contains keys:
"data": log file contents
"subid": subjob ID
"jobid": job ID

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

qb::stderr(@ids)

qb::submit

Purpose

Submits a list of jobs to be dispatched by the Supervisor.

 

Prototype

qb::submit(job)

 

Parameters

job

Hash reference containing the job parameters. Must contain at minimum a $job{prototype} value containing the Job Type to execute.

Results

$_ is a pointer to the job hash.$_->{ID} is the ID of the submitted job.

 

Comments

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

my $job = { "name" => "job name", "priority" => "12433", "cluster" => "/project/rnd", "requirements" => "host.name == qb003 \ and host.os eq Linux", "prototype" => "cmdline", "package" => {"cmdline" => "sleep 100"}};

qb::submit($job)

qb::submitcallback

Purpose

Submit a job callback to be executed on certain events.

 

Prototype

qb::submit(callback)

 

Parameters

callback

Hash containing the callback parameters.

Results

 

 

Comments

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

qb::submit(%callback)

qb::suspend

Purpose

Sends the SUSPEND signal to running jobs

 

Prototype

qb::suspend(ids)

 

Parameters

ids

a list of job or subjob ids.

Results

 

 

Comments

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

qb::suspend(@ids)

qb::top

Purpose

Moves jobs to the head of execution order queue.

 

Prototype

qb::top(ids)

 

Parameters

ids

a list of job or subjob ids.

Result

 

 

Comments

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

qb::top(@ids)

qb::unblock

Purpose

Unblocks jobs so they can begin executing when hosts become available.

 

Prototype

qb::unblock(ids)

 

Parameters

ids

a list of job or subjob ids.

Results

 

 

Notes

 

 


Example


use lib "$ENV{QBDIR}/api/perl";

use qb;

qb::unblock(@ids)

  • No labels