Added in simple comments. Formatting: Tabs, ws, etc.

include/JobManager.h

@@ -19,7 +19,7 @@
  */
 /** @file JobManager.h
  *
- * Brief description
+ * Singleton class.  Managers all JobWorkers, and their task allocation.  Maintains a FIFO AbstractJob queue.
  *
  */
 
@@ -31,22 +31,52 @@
 #include <QList>
 #include <QMutex>
 
-class JobWorker; //use forward Dec since JobWorker isn't public
+//Forward Decl
+class JobWorker;
 
 class JobManager
 {
 
 public:
+/**
+ * Provides controlled access to the singleton JobManager object.
+ */
 	static JobManager* getInstance();
 
 	virtual ~JobManager();
 
+	/**
+	 * Returns the next AbstractJob in the JobManager's internal FIFO Queue.  If empty, returns NULL.
+	 */
 	AbstractJob* getNextJob();
-	bool hasJobsToWork();
+
+	/**
+	 * Returns a boolean value indicating whether or not the JobManager's internal FIFO Queue contains an AbstractJob that is waiting for execution.
+	 */
+	bool hasNextJob();
+
+	/**
+	 * Returns the JobManager's internal FIFO Queue length.
+	 */
 	quint32 getWorkQueueLen();
+
+	/**
+	 * Places AbstractJob <i>aj</i> into the JobManager's internal FIFO Queue.  If the JobManager is
+	 * currently not accepting AbstractJobs, a warning is issued via the Logging system.
+	 */
 	void submitJob(AbstractJob* aj);
 
+	/**
+	 * Starts all the JobWorkers that were initialized in the JobManager constructor.
+	 */
 	void startup();
+
+	/**
+	 * Sets the JobManager's AcceptJObs flag to false and shuts down all the JobWorkers associated
+	 * with the JobManager.  Optionally, this function will block until all AbstractJobs in the JobManager's
+	 * internal FIFO Queue are executed.  There is a fail-safe built into the optional wait that will prevent a
+	 * stalled job from preventing a JobManager.  Should the fail-safe be tripped a Log entry will be made.
+	 */
 	void shutdown(bool finishJobQueue = true);
 
 private:

src/libJob/JobManager.cxx

@@ -17,17 +17,13 @@
  * License along with this file; see the file named COPYING for more
  * information.
  */
-/** @file JobManager.cxx
- *
- * Singleton.
- *
- */
 
 #include "JobManager.h"
 #include "JobWorker.h"
 #include <QMutexLocker>
 #include <iostream>
 
+//Declares for statics.
 JobManager* JobManager::pInstance = NULL;
 QMutex* JobManager::singletonLock = new QMutex();
 
@@ -39,17 +35,16 @@ JobManager::JobManager()
     this->jobWorkers = new QList<JobWorker*> ();
     this->acceptJobs = false;
 
-    QString text = "Startup.  MAX_JOBWORKERS: " + QString::number(
-	    MAX_JOBWORKERS);
+    QString text = "Startup.  MAX_JOBWORKERS: " + QString::number(MAX_JOBWORKERS);
 
     this->log->logINFO("JobManager", text);
 
     for (quint32 i = 0; i < MAX_JOBWORKERS; ++i) {
-	JobWorker* jw = new JobWorker();
-	this->jobWorkers->append(jw);
+    	JobWorker* jw = new JobWorker();
+    	this->jobWorkers->append(jw);
 
-	text = "Created new JobWorker with ID of " + jw->getWorkerIdAsQString();
-	this->log->logINFO("JobManager", text);
+    	text = "Created new JobWorker with ID of " + jw->getWorkerIdAsQString();
+    	this->log->logINFO("JobManager", text);
     }
 
     text = "Created a total of " + QString::number(this->jobWorkers->size()) + " JobWorkers";
@@ -66,12 +61,13 @@ JobManager::~JobManager()
 
     delete jobWorkers;
 }
+
 void JobManager::startup()
 {
-    for (quint32 i = 0; i < MAX_JOBWORKERS; ++i) {
- 	JobWorker* jw = this->jobWorkers->at(i);
- 	jw->start();
-     }
+    for (quint32 i = 0; i < this->jobWorkers->size(); ++i) {
+    	JobWorker* jw = this->jobWorkers->at(i);
+    	jw->start();
+    }
     this->acceptJobs = true;
 }
 
@@ -84,24 +80,24 @@ void JobManager::shutdown(bool finishJobQueue)
     //TODO These should be moved to preferences eventually.
     quint32 maxWaitTimeSecs = 60;
     quint32 waitTimePerLoopSecs = 5;
-    quint32 maxPasses = maxWaitTimeSecs / waitTimePerLoopSecs;
+    quint32 maxPasses = (maxWaitTimeSecs / waitTimePerLoopSecs);
     quint32 curPasses = 0;
 
     while (this->jobQueue->size() != 0 && finishJobQueue) {
-	this->log->logINFO("JobManager", "Waiting for JobWorkers to process JobQueue. " + QString::number(this->jobQueue->size()) + " items remain...");
-	ThreadUtils::sleep(waitTimePerLoopSecs);
-	++curPasses;
-	if (curPasses >= maxPasses) {
-	    this->log->logINFO("JobManager", "Shutdown Wait time failsafe tripped.  Forcing Shutdown.");
-	    break;
-	}
+    	this->log->logINFO("JobManager", "Waiting for JobWorkers to process JobQueue. " + QString::number(this->jobQueue->size()) + " items remain...");
+    	ThreadUtils::sleep(waitTimePerLoopSecs);
+    	++curPasses;
+    	if (curPasses >= maxPasses) {
+    		this->log->logINFO("JobManager", "Shutdown Wait-time fail safe reached.  Forcing Shutdown.");
+    		break;
+    	}
     }
 
     //loop through workers, shut them down individually. Then empty worker list
     while (!this->jobWorkers->isEmpty()) {
-	JobWorker* jw = this->jobWorkers->front();
-	jw->shutdown();
-	this->jobWorkers->pop_front();
+    	JobWorker* jw = this->jobWorkers->front();
+		jw->shutdown();
+		this->jobWorkers->pop_front();
     }
 
     this->log->logINFO("JobManager", "All JobWorkers Stopped. " + QString::number(this->jobQueue->size()) + " items in jobQueue remain...");
@@ -112,16 +108,17 @@ JobManager* JobManager::getInstance()
     QMutexLocker locker(JobManager::singletonLock);
 
     if (!JobManager::pInstance) {
-	pInstance = new JobManager();
+    	pInstance = new JobManager();
     }
     return JobManager::pInstance;
 }
 
 void JobManager::submitJob(AbstractJob* job)
 {
     if (this->acceptJobs == false) {
-	log->logWARNING("JobManager", "Job not queued. JobWorkers are currently not working.");
-	return; //TODO perhaps return a bool??
+    	this->log->logWARNING("JobManager", "Job not queued. JobWorkers are currently not working.");
+		 //TODO perhaps return a bool??
+    	return;
     }
 
     QMutexLocker locker(this->queueLock);
@@ -132,21 +129,21 @@ AbstractJob* JobManager::getNextJob()
 {
     QMutexLocker locker(this->queueLock);
     if (!this->jobQueue->isEmpty()) {
-	return this->jobQueue->takeFirst();
-    }
-    else {
-	return NULL;
+    	return this->jobQueue->takeFirst();
+    } else {
+    	return NULL;
     }
 }
 
-bool JobManager::hasJobsToWork()
+bool JobManager::hasNextJob()
 {
     QMutexLocker locker(this->queueLock);
     return !this->jobQueue->isEmpty();
 }
 
 quint32 JobManager::getWorkQueueLen()
 {
+	QMutexLocker locker(this->queueLock);
     return this->jobQueue->size();
 }
 

src/libJob/JobWorker.cxx

@@ -49,31 +49,33 @@ void JobWorker::run()
 
     this->status = WORKER_READY;
 
-    //TODO there must be a more dynamic way to have the workers idle other than a sleep
+    //TODO There MUST be a more dynamic way to have the workers idle other than a sleep
+    //NOTE Semaphore perhaps?  QT Signal?
     while (this->runCmd) {
+    	this->status = WORKER_READY;
+    	if (!jm->hasNextJob()) {
+    		//TODO put the 100ms sleep into preferences, or make it dynamic.
+    		this->msleep(100);
 
-	this->status = WORKER_READY;
-	if (!jm->hasJobsToWork()) {
-	    this->msleep(100);
-	}
-	else {
-	    this->status = WORKER_WORKING;
-	    AbstractJob* job = jm->getNextJob();
+    	} else {
+    		this->status = WORKER_WORKING;
+    		AbstractJob* job = jm->getNextJob();
 
-	    if (job == NULL) {
-		continue;
-	    }
+    		if (job == NULL) {
+    			//TODO put in an error trap here.  jm->hasNextJob() returned TRUE, but the job returned was NULL?!
+				continue;
+    		}
 
-//	    QString text = "JobWorker " + this->getWorkerIdAsQString()
+//	   	 	QString text = "JobWorker " + this->getWorkerIdAsQString()
 //		    + " is working Job with ID of " + QString::number(job->getJobId());
-//	    this->log->logINFO("JobWorker", text);
+//	   		 this->log->logINFO("JobWorker", text);
 
-	    JobResult result = job->doJob();
+    		JobResult result = job->doJob();
 
-	    //TODO log the result?
+    		//TODO log the result of the job for debugging?
+    	}
+    	this->status = WORKER_READY;
 
-	}
-	this->status = WORKER_READY;
     }
     this->status = WORKER_NOTREADY;
 }
@@ -95,12 +97,12 @@ QUuid JobWorker::getWorkerId()
 
 QString JobWorker::getWorkerIdAsQString()
 {
-    return this->workerId.toString();
+    return this->getWorkerId().toString();
 }
 
 std::string JobWorker::getWorkerIdAsStdString()
 {
-    return this->workerId.toString().toStdString();
+    return this->getWorkerIdAsQString().toStdString();
 }
 
 void JobWorker::shutdown()

src/libJob/JobWorker.h

@@ -19,40 +19,68 @@
  */
 /** @file JobWorker.h
  *
- * Brief description
+ * Represents a single QThread implementation that is managed by the
+ * JobManager and executes AbstractJob objects.
  *
  */
 
 #ifndef __JOBWORKER_H__
 #define __JOBWORKER_H__
 
+//TODO Move this to preferences.
 #define MAX_JOBWORKERS 5
 
 #include "libutility.h"
 #include <QThread>
 #include <QUuid>
 #include <string>
 
-enum JobWorkerStatus
-{
+enum JobWorkerStatus {
 	WORKER_NOTREADY, WORKER_READY, WORKER_WORKING
 };
 
-class JobWorker: public QThread
-{
+class JobWorker: public QThread {
 
 public:
+	/**
+	 * Standard Constructor.  Instantiates a new JobWorker with a unique ID.
+	 */
 	JobWorker();
 	virtual ~JobWorker();
 
+	/**
+	 * Override of QThread.run(). Starts JobWorker execution.
+	 */
 	void run();
 
+	/**
+	 * Returns the JobWorker's current status (WORKER_NOTREADY, WORKER_READY, WORKER_WORKING)
+	 */
 	JobWorkerStatus getStatus();
+
+	/**
+	 * Sets the JobWorker's runCmd flag to FALSE.
+	 */
 	void shutdown();
+
+	/**
+	 * Gets the UUID of the JobWorker.
+	 */
 	QUuid getWorkerId();
+
+	/**
+	 * Gets the UUID of the JobWorker as a QString.
+	 */
 	QString getWorkerIdAsQString();
+
+	/**
+	 * Gets the UUID of the JobWorker as a STL string.
+	 */
 	std::string getWorkerIdAsStdString();
 
+	/**
+	 * Returns TRUE if the JobWorker's status is currently WORKER_READY
+	 */
 	bool isIdle();
 
 private: