MoleQueue  0.8.0
 All Classes Functions Variables Enumerations Enumerator Pages
Public Slots | Signals | Public Member Functions | Static Public Member Functions | Protected Slots | Protected Member Functions | Protected Attributes | List of all members
Queue Class Referenceabstract

#include <molequeue/queue.h>

Inheritance diagram for Queue:
QueueLocal QueueRemote QueueRemoteSsh QueueUit QueuePbs QueueSge QueueSlurm

Public Slots

virtual bool submitJob (MoleQueue::Job job)=0
 
virtual void killJob (MoleQueue::Job job)=0
 
virtual void setLaunchTemplate (const QString &script)
 
virtual void setLaunchScriptName (const QString &scriptName)
 

Signals

void programAdded (const QString &name, MoleQueue::Program *program)
 
void programRemoved (const QString &name, MoleQueue::Program *program)
 
void programRenamed (const QString &newName, Program *prog, const QString &oldName)
 
void nameChanged (const QString &newName, const QString &oldName)
 

Public Member Functions

Serverserver ()
 
const Serverserver () const
 
QueueManagerqueueManager ()
 
const QueueManagerqueueManager () const
 
virtual void setName (const QString &newName)
 
QString name () const
 
virtual QString typeName () const
 
bool readSettings (const QString &filePath)
 
bool writeSettings () const
 
bool exportSettings (const QString &fileName, bool includePrograms=true) const
 
bool importSettings (const QString &fileName, bool includePrograms=true)
 
QString stateFileName () const
 
virtual bool writeJsonSettings (QJsonObject &value, bool exportOnly, bool includePrograms) const
 
virtual bool readJsonSettings (const QJsonObject &value, bool importOnly, bool includePrograms)
 
virtual
AbstractQueueSettingsWidget
settingsWidget ()
 
bool addProgram (Program *newProgram, bool replace=false)
 
bool removeProgram (Program *programToRemove)
 
bool removeProgram (const QString &programName)
 
ProgramlookupProgram (const QString &programName) const
 
QStringList programNames () const
 
QList< Program * > programs () const
 
int numPrograms () const
 
virtual QString launchTemplate () const
 
QString launchScriptName () const
 
int jobFailureCount (IdType moleQueueId) const
 
virtual void replaceKeywords (QString &launchScript, const Job &job, bool addNewline=true)
 

Static Public Member Functions

static QString queueTypeFromFile (const QString &mqqFile)
 

Protected Slots

virtual void jobAboutToBeRemoved (const MoleQueue::Job &job)
 
void programNameChanged (const QString &newName, const QString &oldName)
 
void cleanLocalDirectory (const MoleQueue::Job &job)
 

Protected Member Functions

 Queue (const QString &queueName="Undefined", QueueManager *parentManager=0)
 
bool writeInputFiles (const Job &job)
 
bool addJobFailure (IdType moleQueueId)
 
void clearJobFailures (IdType moleQueueId)
 

Protected Attributes

QueueManagerm_queueManager
 
Serverm_server
 
QString m_name
 
QString m_launchTemplate
 
QString m_launchScriptName
 
QMap< QString, Program * > m_programs
 
QMap< IdType, IdType > m_jobs
 
QMap< IdType, int > m_failureTracker
 

Detailed Description

Abstract interface for queuing systems.

Author
Marcus D. Hanwell, David C. Lonie

The Queue interface defines interactions with a distributed resource management system, such as job submission and job status updates. Each Queue object manages a set of Program instances, which contain information about the related task of actually running an executable to do work.

Constructor & Destructor Documentation

Queue ( const QString &  queueName = "Undefined",
QueueManager parentManager = 0 
)
explicitprotected

Protected constructor. Use QueueManager:::addQueue() method to create new Queue objects.

Member Function Documentation

Server* server ( )
Returns
The parent Server
const Server* server ( ) const
Returns
The parent Server
QueueManager* queueManager ( )
Returns
The parent QueueManager
const QueueManager* queueManager ( ) const
Returns
The parent Server
virtual void setName ( const QString &  newName)
virtual

Set the name of the queue. This should be unique, and will be used in the GUI to refer to this queue.

QString name ( ) const

Get the name of the queue.

virtual QString typeName ( ) const
virtual

Returns the type of the queue as a string.

Reimplemented in QueueUit, QueueLocal, QueuePbs, QueueSge, and QueueSlurm.

bool readSettings ( const QString &  filePath)

Read settings for the queue, done early on at startup.

Parameters
filePathPath to the .mqq file with the queue settings.

This method calls readJsonSettings to perform the actual setting of state information. Subclasses should reimplement that method.

bool writeSettings ( ) const

Write settings for the queue, done just before closing the server. The settings are written to [server's local working directory]/config/queues/[queuename].mqq

This method calls writeJsonSettings to perform the actual collection of state information. Subclasses should reimplement that method.

bool exportSettings ( const QString &  fileName,
bool  includePrograms = true 
) const

Write this Queue's configuration to the .mqq file fileName. Sensitive data (such as usernames, etc) and mutatable state data (like current jobs) are not written, see writeSettings() if these are needed.

Parameters
includeProgramsExport this queue's programs as well. Default: true

This method calls writeJsonSettings to perform the actual collection of state information. Subclasses should reimplement that method.

bool importSettings ( const QString &  fileName,
bool  includePrograms = true 
)

Set this Queue's configuration using the the .mqq file fileName. Sensitive data (such as usernames, etc) and mutatable state data (like current jobs) are not read, see readSettings() if these are needed.

Parameters
includeProgramsImport any programs contained in the importer. Default: true

This method calls readJsonSettings to perform the actual setting of state information. Subclasses should reimplement that method.

static QString queueTypeFromFile ( const QString &  mqqFile)
static
Parameters
mqqFileFilename of the mqq (MoleQueue Queue) file.
Returns
Return the type of queue that is stored in the .mqq file.
QString stateFileName ( ) const
Returns
The name of the persistant state file used to store this Queue's configuration.
virtual bool writeJsonSettings ( QJsonObject &  value,
bool  exportOnly,
bool  includePrograms 
) const
virtual

writeJsonSettings Write the queue's internal state into a JSON object.

Parameters
valueTarget JSON object.
exportOnlyIf true, instance specific information (e.g. currently running jobs, login details, etc) is omitted.
includeProgramsWhether or not to include the Queue's program configurations.
Returns
True on success, false on failure.

Reimplemented in QueueUit, QueueLocal, QueueRemoteSsh, and QueueRemote.

virtual bool readJsonSettings ( const QJsonObject &  value,
bool  importOnly,
bool  includePrograms 
)
virtual

readJsonSettings Initialize the queue's internal state from a JSON object.

Parameters
valueSource JSON object.
importOnlyIf true, instance specific information (e.g. currently running jobs, login details, etc) is ignored.
includeProgramsWhether or not to include the Queue's program configurations.
Returns
True on success, false on failure.
Note
When reimplementing this method, verify and parse the Json object into temporary variables, then call the base class implementation and only modify the queue if the call returns true.

Reimplemented in QueueUit, QueueLocal, QueueRemoteSsh, and QueueRemote.

virtual AbstractQueueSettingsWidget* settingsWidget ( )
virtual

Returns a widget that can be used to configure the settings for the queue.

Reimplemented in QueueRemoteSsh, QueueUit, QueueLocal, and QueueRemote.

bool addProgram ( Program newProgram,
bool  replace = false 
)

Add a new program to the queue. Program names must be unique in each queue, as they are used to specify which program will be used.

Note
This Queue instance will take ownership and reparent newProgram.
Parameters
programThe program to be added to the queue.
replaceDefaults to false, if true replace any program with the same name in this queue.
Returns
True on success, false on failure.
bool removeProgram ( Program programToRemove)

Attempt to remove a program from the queue. The program name is used as the criteria to decice which object to remove.

Parameters
programThe program to be removed from the queue.
Returns
True on success, false on failure.
bool removeProgram ( const QString &  programName)

Attempt to remove a program from the queue. The program name is used as the criteria to decide which object to remove.

Parameters
nameThe name of the program to be removed from the queue.
Returns
True on success, false on failure.
Program* lookupProgram ( const QString &  programName) const

Retrieve the program object associated with the supplied name.

Parameters
nameThe name of the program.
Returns
The Program object, a null pointer is returned if the requested program is not in this queue.
QStringList programNames ( ) const
Returns
A list of program names available through this queue.
QList<Program *> programs ( ) const
Returns
A list of the available Program objects.
int numPrograms ( ) const
Returns
The number of programs belonging to this Queue.
virtual QString launchTemplate ( ) const
virtual
Returns
A string containing a template for the launcher script. For remote queues, this will be a batch script for the queuing system, for local queues this will be a shell script (unix) or batch script (windows).

It should contain the token "$$programExecution$$", which will be replaced with program-specific launch details.

QString launchScriptName ( ) const
Returns
The filename for the launcher script. For remote queues, this will be a batch script for the queuing system, for local queues this will be a shell script (unix) or batch script (windows).
int jobFailureCount ( IdType  moleQueueId) const
Parameters
moleQueueIdMoleQueue id of Job of interest.
Returns
The number of time the job has failed if it has encountered an error and is being retried. 0 if the job has not encountered an error, or has exceeded three retries.
virtual void replaceKeywords ( QString &  launchScript,
const Job job,
bool  addNewline = true 
)
virtual

replaceKeywords Replace $$keywords$$ in launchScript with queue/job specific values.

Parameters
launchScriptLaunch script to complete.
jobJob data to use.

Reimplemented in QueueRemote.

void programAdded ( const QString &  name,
MoleQueue::Program program 
)
signal

Emitted when a new program is added to the Queue.

Parameters
nameName of the program.
programPointer to the newly added Program object.
void programRemoved ( const QString &  name,
MoleQueue::Program program 
)
signal

Emitted when a program is removed from the queue.

Parameters
nameName of the program
programPointer to the removed Program object.
Warning
The pointer should not be dereferenced, as this signal is often associated with program deletion.
void programRenamed ( const QString &  newName,
Program prog,
const QString &  oldName 
)
signal

programRenamed Emitted when a program is renamed.

void nameChanged ( const QString &  newName,
const QString &  oldName 
)
signal

Emitted when the name of the queue is changed.

virtual bool submitJob ( MoleQueue::Job  job)
pure virtualslot

Writes input files and submits a new job to the queue.

Parameters
jobJob to submit.
Returns
True on success, false on failure.
See Also
jobSubmitted
virtual void killJob ( MoleQueue::Job  job)
pure virtualslot

killJob Stop the job and remove from the queue. Set the JobState to Canceled.

Parameters
jobJob to kill.
virtual void setLaunchTemplate ( const QString &  script)
virtualslot

Update the launch script template.

Parameters
scriptThe new launch template.
See Also
launchTemplate
virtual void setLaunchScriptName ( const QString &  scriptName)
virtualslot

Update the launch script name.

Parameters
scriptNameThe new launch script name.
See Also
launchTemplate
launchScript
virtual void jobAboutToBeRemoved ( const MoleQueue::Job job)
protectedvirtualslot

Called when the JobManager::jobAboutToBeRemoved signal is emitted to remove any internal references to the job. Subclasses should reimplement if they hold any state about owned jobs.

void programNameChanged ( const QString &  newName,
const QString &  oldName 
)
protectedslot

Update internal data structures when the name of a program changes.

void cleanLocalDirectory ( const MoleQueue::Job job)
protectedslot

Delete the local working directory of Job.

bool writeInputFiles ( const Job job)
protected

Write the input files for job to the local working directory.

bool addJobFailure ( IdType  moleQueueId)
protected

addJobFailure Call this when a job encounters a problem but will be retried (e.g. a possible networking failure). The failure will be recorded and the return value will indicate whether to retry the job or not. If this function returns true, the job has failed less than 3 times and an attempt should be made to retry. If it returns false, the job has exceeded the maximum number of retries and should be aborted. The failure count will be reset and an error will be logged if the maximum retries are exceeded.

Parameters
moleQueueId
Returns
True if the job should be retried, false otherwise.
See Also
jobFailureCount
clearJobFailures
void clearJobFailures ( IdType  moleQueueId)
protected

clearJobFailures Remove all recorded job failures for a job. This does not necessarily mean that the job is successful, but that it is no longer being retried.

Parameters
moleQueueIdMoleQueue id of job
See Also
addJobFailure
jobFailureCount

Member Data Documentation

QMap<IdType, IdType> m_jobs
protected

Lookup table for jobs that are using this Queue. Maps JobId to MoleQueueId.

QMap<IdType, int> m_failureTracker
protected

Keeps track of the number of times a job has failed (MoleQueueId to #failures). Once a job fails three times, it will no longer retry.


The documentation for this class was generated from the following file: