cctools
batch_queue.h File Reference

Batch queue submission library. More...

#include <sys/stat.h>
#include <inttypes.h>
#include <stdint.h>
#include <time.h>
#include "batch_job.h"
#include "batch_file.h"
#include "batch_job_info.h"
#include "batch_wrapper.h"
#include "jx.h"
#include "rmsummary.h"

Go to the source code of this file.

Typedefs

typedef int64_t batch_queue_id_t
 An integer type indicating a unique batch job number.
 

Enumerations

enum  batch_queue_type_t {
  BATCH_QUEUE_TYPE_LOCAL ,
  BATCH_QUEUE_TYPE_CONDOR ,
  BATCH_QUEUE_TYPE_VINE ,
  BATCH_QUEUE_TYPE_WORK_QUEUE ,
  BATCH_QUEUE_TYPE_UGE ,
  BATCH_QUEUE_TYPE_SLURM ,
  BATCH_QUEUE_TYPE_CLUSTER ,
  BATCH_QUEUE_TYPE_MOAB ,
  BATCH_QUEUE_TYPE_PBS ,
  BATCH_QUEUE_TYPE_LSF ,
  BATCH_QUEUE_TYPE_TORQUE ,
  BATCH_QUEUE_TYPE_AMAZON ,
  BATCH_QUEUE_TYPE_K8S ,
  BATCH_QUEUE_TYPE_DRYRUN ,
  BATCH_QUEUE_TYPE_UNKNOWN = -1
}
 Indicates which type of batch submission to use. More...
 

Functions

struct batch_queuebatch_queue_create (batch_queue_type_t type, const char *ssl_key_file, const char *ssl_cert_file)
 Create a new batch queue.
 
batch_queue_id_t batch_queue_submit (struct batch_queue *q, struct batch_job *task)
 Submit a batch job.
 
batch_queue_id_t batch_queue_wait (struct batch_queue *q, struct batch_job_info *info)
 Wait for any batch job to complete.
 
batch_queue_id_t batch_queue_wait_timeout (struct batch_queue *q, struct batch_job_info *info, time_t stoptime)
 Wait for any batch job to complete, with a timeout.
 
int batch_queue_remove (struct batch_queue *q, batch_queue_id_t jobid)
 Remove a batch job.
 
batch_queue_type_t batch_queue_type_from_string (const char *str)
 Converts a string into a batch queue type.
 
const char * batch_queue_type_to_string (batch_queue_type_t t)
 Converts a batch queue type to a string.
 
void batch_queue_set_logfile (struct batch_queue *q, const char *logfile)
 Set the log file used by the batch queue.
 
void batch_queue_set_option (struct batch_queue *q, const char *what, const char *value)
 Add extra options to pass to the underlying batch system.
 
void batch_queue_set_feature (struct batch_queue *q, const char *what, const char *value)
 Expresses support for feature in the underlying batch system.
 
void batch_queue_set_int_option (struct batch_queue *q, const char *what, int value)
 As batch_queue_set_option, but allowing an integer argument.
 
const char * batch_queue_get_option (struct batch_queue *q, const char *what)
 Get batch queue options.
 
int batch_queue_option_is_yes (struct batch_queue *q, const char *what)
 Check if option is set to yes.
 
const char * batch_queue_supports_feature (struct batch_queue *q, const char *what)
 Get batch queue feature.
 
batch_queue_type_t batch_queue_get_type (struct batch_queue *q)
 Get batch queue type.
 
void batch_queue_delete (struct batch_queue *q)
 Delete a batch queue.
 
const char * batch_queue_type_string ()
 Returns the list of queue types supported by this module.
 
int batch_queue_port (struct batch_queue *q)
 Returns the port number of the batch queue.
 

Detailed Description

Batch queue submission library.

This module implements an abstract interface to submit batch jobs to a variety of underlying queuing systems, including including local processes, HTCondor, TaskVine, Work Queue, UGE, PBS, SLURM Amazon EC2, and others. This simplifies the construction of workflow systems and other parallel computing systems that need a simple form of distributed process execution.

Basic use is as follows:

// Create a queue for submitting to HTCondor.
struct batch_queue *queue = batch_queue_create(BATCH_QUEUE_TYPE_CONDOR);

// Define a batch job consiting of a command with input and output files.
struct batch_job *job = batch_job_create(queue);
batch_job_set_command(job,"grep needle words.txt > output.txt");
batch_job_add_input_file(job,"needle","needle");
batch_job_add_input_file(job,"/usr/share/dict/words","words.txt");
batch_job_add_output_file(job,"output.txt","output.txt");

// Submit the job to the queue, which returns a jobid 
batch_job_id_t jobid = batch_queue_submit(queue,job);
printf("jobid %" PRIbjid" submitted\n",jobid);

// Wait for a job to complete, which returns the jobid and info.
struct batch_job_info info;
jobid = batch_queue_wait(queue,&info);

printf("jobid %" PRIbjid" completed\n",jobid);

// Delete objects when done.
batch_job_delete(job);
batch_queue_delete(queue);

Typedef Documentation

◆ batch_queue_id_t

typedef int64_t batch_queue_id_t

An integer type indicating a unique batch job number.

Enumeration Type Documentation

◆ batch_queue_type_t

Indicates which type of batch submission to use.

Enumerator
BATCH_QUEUE_TYPE_LOCAL 

Batch jobs will run as local processes.

BATCH_QUEUE_TYPE_CONDOR 

Batch jobs will be sent to Condor pool.

BATCH_QUEUE_TYPE_VINE 

Batch jobs will be sent to TaskVine manager.

BATCH_QUEUE_TYPE_WORK_QUEUE 

Batch jobs will be sent to Work Queue manager.

BATCH_QUEUE_TYPE_UGE 

Batch jobs will be sent to Univa Grid Engine.

BATCH_QUEUE_TYPE_SLURM 

Batch jobs will be send to the SLURM scheduler.

BATCH_QUEUE_TYPE_CLUSTER 

Batch jobs will be sent to a user-defined cluster manager.

BATCH_QUEUE_TYPE_MOAB 

Batch jobs will be sent to the Moab Workload Manager.

BATCH_QUEUE_TYPE_PBS 

Batch jobs will be send to the PBS scheduler.

BATCH_QUEUE_TYPE_LSF 

Batch jobs will be sent to the LSF scheduler.

BATCH_QUEUE_TYPE_TORQUE 

Batch jobs will be send to the Torque scheduler.

BATCH_QUEUE_TYPE_AMAZON 

Batch jobs will be run inside Amazon EC2 Instances.

BATCH_QUEUE_TYPE_K8S 

Batch jobs will be run inside Kubernetes pods.

BATCH_QUEUE_TYPE_DRYRUN 

Batch jobs will not actually run.

BATCH_QUEUE_TYPE_UNKNOWN 

An invalid batch queue type.

Function Documentation

◆ batch_queue_create()

struct batch_queue * batch_queue_create ( batch_queue_type_t  type,
const char *  ssl_key_file,
const char *  ssl_cert_file 
)

Create a new batch queue.

Parameters
typeThe type of the queue.
ssl_key_fileThe location of the queue manager's ssl key file, if it has one.
ssl_key_fileThe location of the queue manager's ssl certiciate file, if it has one.
Returns
A new batch queue object on success, null on failure.

◆ batch_queue_submit()

batch_queue_id_t batch_queue_submit ( struct batch_queue q,
struct batch_job task 
)

Submit a batch job.

Parameters
qThe queue to submit to.
taskThe job description to submit.
resourcesThe computational resources needed by the job.
Returns
On success, returns a positive unique identifier for the batch job. On failure, returns a negative number. Zero is not a valid batch job id and indicates an internal failure.

◆ batch_queue_wait()

batch_queue_id_t batch_queue_wait ( struct batch_queue q,
struct batch_job_info info 
)

Wait for any batch job to complete.

Blocks until a batch job completes. Note Submit may return 0 as a valid jobid. As of 04/18 wait will not return 0 as a valid jobid. Wait returning 0 indicates there are no waiting jobs in this queue.

Parameters
qThe queue to wait on.
infoPointer to a batch_job_info structure that will be filled in with the details of the completed job.
Returns
If greater than zero, indicates the jobid of the completed job. If equal to zero, there were no more jobs to wait for. If less than zero, the operation was interrupted by a system event, but may be tried again.

◆ batch_queue_wait_timeout()

batch_queue_id_t batch_queue_wait_timeout ( struct batch_queue q,
struct batch_job_info info,
time_t  stoptime 
)

Wait for any batch job to complete, with a timeout.

Blocks until a batch job completes or the current time exceeds stoptime. Note Submit may return 0 as a valid jobid. As of 04/18 wait will not return 0 as a valid jobid. Wait returning 0 indicates there are no waiting jobs in this queue.

Parameters
qThe queue to wait on.
infoPointer to a batch_job_info structure that will be filled in with the details of the completed job.
stoptimeAn absolute time at which to stop waiting. If less than or equal to the current time, then this function will check for a complete job but will not block.
Returns
If greater than zero, indicates the jobid of the completed job. If equal to zero, there were no more jobs to wait for. If less than zero, the operation timed out or was interrupted by a system event, but may be tried again.

◆ batch_queue_remove()

int batch_queue_remove ( struct batch_queue q,
batch_queue_id_t  jobid 
)

Remove a batch job.

This call will start the removal process. You must still call batch_queue_wait to wait for the removal to complete.

Parameters
qThe queue to remove from.
jobidThe job to be removed.
Returns
Greater than zero if the job exists and was removed, zero otherwise.

◆ batch_queue_type_from_string()

batch_queue_type_t batch_queue_type_from_string ( const char *  str)

Converts a string into a batch queue type.

Parameters
strA string listing all of the known batch queue types (which changes over time.)
Returns
The batch queue type corresponding to the string, or BATCH_QUEUE_TYPE_UNKNOWN if the string is invalid.

◆ batch_queue_type_to_string()

const char * batch_queue_type_to_string ( batch_queue_type_t  t)

Converts a batch queue type to a string.

Parameters
tA batch_queue_type_t.
Returns
A string corresponding to the batch queue type.

◆ batch_queue_set_logfile()

void batch_queue_set_logfile ( struct batch_queue q,
const char *  logfile 
)

Set the log file used by the batch queue.

This is an optional call that will only affect batch queue types that use an internal logfile; currently only Condor.

Parameters
qThe batch queue to adjust.
logfileName of the logfile to use.

◆ batch_queue_set_option()

void batch_queue_set_option ( struct batch_queue q,
const char *  what,
const char *  value 
)

Add extra options to pass to the underlying batch system.

This call specifies additional options to be passed to the batch system each time a job is submitted. It may be called once to apply to all subsequent jobs, or it may be called before each submission. If the queue type is BATCH_QUEUE_TYPE_CONDOR, the options must be valid submit file properties like requirements = (Memory>100). If the batch queue type is BATCH_QUEUE_TYPE_UGE, the extra text will be added as options to the qsub command. This call has no effect on other queue types.

Parameters
qThe batch queue to adjust.
whatThe key for option.
valueThe value of the option.

◆ batch_queue_set_feature()

void batch_queue_set_feature ( struct batch_queue q,
const char *  what,
const char *  value 
)

Expresses support for feature in the underlying batch system.

This call specifies features that are supported by this batch system for use in exterior systems. Used within batch_queue_* for the specific batch system.

Parameters
qThe batch queue to adjust.
whatThe key for feature.
valueThe value of the feature.

◆ batch_queue_set_int_option()

void batch_queue_set_int_option ( struct batch_queue q,
const char *  what,
int  value 
)

As batch_queue_set_option, but allowing an integer argument.

Parameters
qThe batch queue to adjust.
whatThe key for option.
valueThe value of the option.

◆ batch_queue_get_option()

const char * batch_queue_get_option ( struct batch_queue q,
const char *  what 
)

Get batch queue options.

This call returns the additional options to be passed to the batch system each time a job is submitted.

Parameters
qThe batch queue.
whatThe option key.
Returns
The option value.

◆ batch_queue_option_is_yes()

int batch_queue_option_is_yes ( struct batch_queue q,
const char *  what 
)

Check if option is set to yes.

Parameters
qThe batch queue.
whatThe option key.
Returns
1 if option is yes, 0 if unset or not set to yes.

◆ batch_queue_supports_feature()

const char * batch_queue_supports_feature ( struct batch_queue q,
const char *  what 
)

Get batch queue feature.

This call returns a valid const char if the feaute specified is supported by the given queue type.

Parameters
qThe batch queue.
whatThe option key.
Returns
The option value.

◆ batch_queue_get_type()

batch_queue_type_t batch_queue_get_type ( struct batch_queue q)

Get batch queue type.

This call returns the type of the batch queue.

Parameters
qThe batch queue.
Returns
The type of the batch queue, defined when it was created.

◆ batch_queue_delete()

void batch_queue_delete ( struct batch_queue q)

Delete a batch queue.

Note that this function just destroys the internal data structures, it does not abort running jobs. To properly clean up running jobs, you must call batch_queue_wait until it returns zero, or call batch_queue_remove on all runnings jobs.

Parameters
qThe queue to delete.

◆ batch_queue_type_string()

const char * batch_queue_type_string ( )

Returns the list of queue types supported by this module.

Useful for including in help-option outputs.

Returns
A static string listing the types of queues supported.

◆ batch_queue_port()

int batch_queue_port ( struct batch_queue q)

Returns the port number of the batch queue.

Parameters
qThe batch queue of interest.
Returns
The port number in use, or zero if not applicable.