Job Scheduling Tutorial

The purpose of the Command field is to execute a command that will run a third-party job scheduler to do the work of scheduling and starting a FastX session when the server is ready.  This way, administrators can use their professional level job schedulers to distribute the workload evenly across a cluster.

Job Scheduling Function

function myFilter(input) {
 //This script runs on the server when a start call is issued
 //It's purpose is to return the scheduling command to launch the session through a job scheduler
 
 //The input parameter is an object that you can use to fine tune how to schedule things
 //
 // input.user -- The user's login object. input.user.sub is the user's login name
 // input.admin -- True if the user is an admin
 // input.start -- The data passed to the api call


//to start immediately (do not schedule -- default action) return null
 //return null;

//errors will be returned to the client api call
 //throw new Error ('Scheduler error: test');

//you can use this script to run any command. It will run as the user who is logged in
 //return 'echo hello world!';

//Below is the typical use case for job scheduling: Hooking in your application to schedule a command
 //uncomment your load balancer, or define your own

//Moab Workload Manager
 //let runner = 'mrun';

//LSF
 //let runner = 'bsub';

//SLURM
 //let runner = 'srun';

//This script is what starts the session
 let startScript = '/usr/lib/fastx/3/scripts/start';

//these are the start params. Only command is required, but you should pass at least these
 let startParams = [
 '--command ${ start.command }',
 '--geometry ${ start.geometry }',
 '--name ${ start.name }',
 ].join (' ');
 
 //return a string with the command that you will run
 return [
 runner, 
 startScript, 
 startParams,
 '> /dev/null;',
 'echo Your job has been scheduled',
 ].join (' ');
}

Input Object

The function has one parameter named input.  This parameter is an object that contains information you can use to make your scheduling decisions

input.user

The user’s login object. input.user.sub is the user’s login name

input.admin

True if the user is an admin

input.start

The data passed to the api call

The string to return

The purpose of the job scheduling script is to return a string that will be executed by the user.  The string is executed like any other shell script on linux.  You can use custom variable interpolation to take the user data and add it into the execution string  The variables sent from the start script will be available as in the when executing the script. An example will help clarify

The following example submits a job that starts a FastX session

bsub "/usr/lib/fastx/3/tools/session" --command "${ start.command }" --geometry ${ start.geometry }"

If you return null, FastX will start a session like any other regular session.  This way you can start sessions on the fly and schedule other ones

Variables

The start parameters from the start command are available to be used.

The start parameters have the format ${ start.__paramname__ }

For example

${ start.command } // the start command
${ start.geometry } //the initial geometry
${ start.name } // the name of the session
${ start.params.key1 } //custom parameter 1 sent to the session
${ start.params.key2 } //custom parameter 2 sent to the session

Specifying job scheduling options

Suppose you want to schedule a job on a server with a minimum amount of 15GB RAM available.  The easiest way to do this is to specify this option as a start param (e.g ${ start.params.RAM } ).  Then in your command add it as a job scheduler option