Scheduler Proxy Interfaces

Scheduler proxy supports following new graphical interface functions. The scheduler specific prefix of each function is not shown in this listing.

void Initialize(const std::string& config):

Initialize the proxy library for scheduler interaction. The config argument contains scheduler specific initialization information.

int CheckEnvironment(std::string& msg):

Check the environment in which the proxy library is running.

Returns 0 (success) if the environment is appropriate for submitting jobs to the scheduler.
Returns a non-zero error code if the environment is incorrect. If a non-zero error code is returned, an error message to display to the user is written to the msg argument.

int GetSchedulerInfo(std::string& msg, std::string& schedulerName, std::string& schedulerDescription, std::string& schedulerVersion):

This function returns some basic information about the scheduler with which the scheduler proxy library interacts.

On success, 0 is returned, and the scheduler name, scheduler description, and scheduler version are written to the schedulerName, schedulerDescription and schedulerVersion arguments.
On failure, a non-zero error code is returned, and an error message to display to the user is written to the msg argument.

int GetComputeResourceAttributes(std::string& msg, AttributeDefinitionsStruct& attributeDefs):

The Compute Resource tab or the Submit Job To dialog box allows the user to specify scheduler specific resources. This function returns the information used to create and populate the Compute Resource tab.

Submit Job To window, Compute Resources tab

Each line in the dialog box is defined by a single attribute definition in the attributeDefs argument. An attribute definition defines the name and description of an attribute, as well as information about the allowed values and the default value. In general, only the most commonly specified job attributes are included in the attributeDefs argument.

On success, 0 is returned, and the attribute definitions are written to the attributeDefs argument.
On failure, a non-zero error code is returned, and an error message to display to the user is written to the msg argument.
If the scheduler proxy library does not support any attributes using this approach, the attributeDefs argument will contain no attribute definitions, and 0 will be returned.

int AbortJob(std::string& msg, const std::string& jobID, bool force, const SubmissionUserStruct& submissionUser):

This function requests the scheduler to abort a job identified by the jobID argument. If the force argument is true, then errors should be ignored (the exact behavior is scheduler specific). The submissionUser argument contains information about the client user (the user running the Desktop process). The request to abort the job should run in the context of this user. If no user is specified, then the request to abort the job runs as the user of the process or thread running the function.

If the request is successfully submitted, then 0 is returned.
If there is an error, then a non-zero error code is returned, and an error message to display to the user is written to the msg argument.

int SubmitUniformJob(std::string& msg, std::string& jobID, const CmdLineStruct& cmdLineInfo, const JobParallelizationStruct& jobParallelization, const UniformComputeResourcesStruct& computeResources, const JobOptionsStruct& jobOptions, const JobAtributesStruct& jobAttributes, const SubmissionUserStruct& submissionUser,const IJobParameters* jobParametersCB):

This function submits a job to the scheduler.

On success, 0 is returned, and the job identifier of the newly submitted job is written to the jobID argument.
On failure, a non-zero error code is returned, and an error message to display to the user is written to the msg argument.

This function is used to submit jobs to the scheduler in which the resources allocated to the job are uniformly distributed across the nodes allocated to the job. All other arguments are input arguments, and they are described below:

The cmdLineInfo argument contains the command line arguments. The first argument is the command name.

The jobParallelization argument contains information on how the job should be parallelized. It contains the following integral parameters:

the total number of distributed engines,
the number of cores to allocate for each distributed engine,
the maximum number of engines to allocate to a single node (optional), and
the number of cores to allocated for the non-distributed portion of the analysis.
It also contains a boolean parameter indicating whether nodes used for this job should be exclusively allocated to this job.

The computeResources argument is a reference to an object of type UniformComputeResourcesStruct. This struct contains zero or more resource attribute settings for the job. Each resource attribute setting consists or a resource name and a resource value. The resource name is the name of one of the resources defined in the AttributeDefinitionsStruct filled in by the GetComputeResourceAttributes() function. The resource attribute value is the value specified for the resource attribute by the user using the Compute Resource tab of the Submit Job To dialog box. If no resource attributes are specified by the user in this dialog box, then the computeResources argument will contain no resource attribute settings.

The jobOptions argument contains the environment variable settings for the job.

The jobAttributes argument contains job submission attributes which are not necessarily related to the compute resources allocated to the job. The job name and the requested job priority are included in this data structure.

The Scheduler Options tab of the Submit Job To dialog box allows the user to either specify additional job submission options or to specify all submission options, replacing the settings from the other Submit Job To dialog box controls.

Submit Job To window, Scheduler Options tab.

The user specified submission options are included in this data structure, as well as a boolean setting indicating whether the user specified options are in addition to the automatically generated options, or whether they replace the automatically generated submission options.

The submissionUser argument contains information about the client user (the user running the Desktop process). The job is submitted to the scheduler to run as this user.

The jobParametersCB argument is a pointer to an object that implements the IJobParameters interface. This interface allows the scheduler proxy library to get additional information about the job. Specifically, the GetWorkingDirectory() interface function returns the working directory to be used for the job.

The cmdLineInfo argument contains the command line arguments. The first argument is the command name.

int SubmitNonUniformJob(std::string& msg, std::string& jobID, const CmdLineStruct& cmdLineInfo, const JobParallelizationStruct& jobParallelization, const NonUniformComputeResourcesStruct& computeResources, const JobOptionsStruct& jobOptions, const JobAtributesStruct& jobAttributes, const SubmissionUserStruct& submissionUser,const IJobParameters* jobParametersCB):

This function submits a job to the scheduler.

On success, 0 is returned, and the job identifier of the newly submitted job is written to the jobID argument.
On failure, a non-zero error code is returned, and an error message to display to the user is written to the msg argument.

This function is used to submit jobs to the scheduler in which the nodes to use and the number of engines to run on each node are specified by the user. All other arguments are input arguments, as for the SubmitUniformJob() function. These input arguments are the same as for the SubmitUniformJob() function, except that the computeResources argument is a reference to a NonUniformComputeResourcesStruct, as described below:

The computeResources argument is a reference to an object of type NonUniformComputeResourcesStruct. This object contains a vector of pairs, where each pair consists of the name of a node in the cluster, and the number of engines to run on the node.

int PreviewUniformJob(std::string& msg, std::string& preview, const CmdLineStruct& cmdLineInfo, const JobParallelizationStruct& jobParallelization, const UniformComputeResourcesStruct& computeResources, const JobOptionsStruct& jobOptions, const JobAtributesStruct& jobAttributes, const SubmissionUserStruct& submissionUser, const IJobParameters* jobParametersCB):

This function is similar to the SubmitUniformJob() function, but instead of submitting the job, text representing how the job will be submitted is written to the preview argument. Typically the preview text includes the job submission command and the contents of the job script created for the job. For some schedulers, this content may not be meaningful, so the text returned could be different.

On success, 0 is returned, and the job preview text is written to the preview argument.
On failure, a non-zero error code is returned, and an error message to display to the user is written to the msg argument.

The other arguments are input arguments with the same meaning as for the SubmitUniformJob() function. The submissionUser argument is ignored for this function.