Module queue

A class for running multiple concurrent jobs.

This module provides the class JobDJ.

The name JobDJ refers to an old implementation of "Job-control for Distributed-Job drivers," and the module name "queue" reflects the fact that added jobs are queued until ready to run.

Like the original JobDJ, its main purpose is to provide for job distribution on multiple hosts. It will keep the number of active jobs on each host at or under the number of processors specified. It can also restart jobs (see documentation on max_retries in the JobDJ.__init__ method).

Additional functionality that is provided in this implementation includes the following:

1. The ability to create dependencies between jobs so that JobDJ can avoid starting a job until its prerequisites are met. See the BaseJob.addPrereq method.
2. The ability to run jobs locally (i.e. not under job control). These jobs can also have dependencies.

Step by step instructions for basic use:

1. Create a JobDJ instance. You can optionally specify the hosts to run the jobs on and the maximum number of jobs for each host by passing a list (host, max_jobs) tuples. By default, the host list is read from the SCHRODINGER_NODEFILE, which is created from the -HOST host list by jlaunch. For example:

      job_dj = queue.JobDJ( [('localhost',1), ('cluster',20)] )
   

2. Add jobs to the JobDJ instance by calling the JobDJ.addJob method. Pass an instance of a BaseJob subclass (such as JobControlJob or SubprocessJob) to the addJob method. For example:

      job_dj.addJob(JobControlJob(["impact", "input1.inp"]))
      # Passing job control commands as a list of strings also works:
      job_dj.addJob(["impact", "input2.inp"])
   

3. Run all jobs with the JobDJ.run method. This is simple:

      job_dj.run()
   

   Alternatively, you can use the updatedJobs generator:

      for job in job_dj.updatedJobs():
          job_dj.dump(filename)
   

   This yields a job every time its status changes. One reason to do things this way is to allow restarting from a pickle. (A JobDJ instance that is restored from a pickle can be started with the run method or updatedJobs generator.)

Because an added job can be a BaseJob instance, additional functionality can be gained by subclassing. For example, the JobDJ instance that a job has been added to can be retrieved with the getJobDJ method and new jobs can be added dynamically by a job at any point during its normal life cycle.

Copyright Schrodinger, LLC. All rights reserved.