Overview

Subclasses of RoseMeshJob holds the logic and state information for a single job that is run in a worker thread by a RoseMeshJobMgr. The run() virtual function is called to do the calculation, and the other functions described here manage a state flag, a common return value, and thread locking.

getResult()

int getResult();

The getResult() function returns a single integer value that represents the outcome of a job. Subclasses can certainly add other reporting functions, but this provides a simple result that can be checked across all jobs.

Zero indicates no result, such as not run or possibly canceled. Negative indicates error, and positive is success. Specific numeric values can be determined by the job.

getState()

int getState()

#define ROSE_MESH_JOB_IDLE	0
#define ROSE_MESH_JOB_QUEUED	1
#define ROSE_MESH_JOB_RUNNING	2
#define ROSE_MESH_JOB_CANCELED	3
#define ROSE_MESH_JOB_DONE	4

The getState() function returns a value that indicates where the job is in its lifecycle. Call this function within a lock/unlock block for thread safety.

A job is created in the IDLE state. It moves to the QUEUED state when submitted for execution. It moves to RUNNING when a thread calls the run() function to execute the job. Finally, it moves to DONE when after the worker threads are finished with it.

If a job is canceled, QUEUED jobs are immediately moved to the DONE state, and RUNNING jobs are moved to the CANCELED state to signal that the job should end early. The run() function can periodically check the state and return if the state is CANCELED.

isActive()

int isActive()

The isActive() function is a convenience wrapper around getState() that locks for thread safety and returns true if the job state is currently queued, running, or running but signaled to cancel. It returns false if the job is either idle or done.

isBlocked()

virtual int isBlocked();

The isBlocked() virtual function is called when a job is queued and waiting to run. The default returns false, and the job will be run as soon as a thread is available. A subclass can override this if two jobs need to run seqientially. If it returns true, the job will be skipped and checked again when the next thread is available.

isCanceled()

int isCanceled()

The isCanceled() function is a convenience wrapper around getState() that locks for thread safety and returns true if the job state is ROSE_MESH_JOB_CANCELED. This can be called within the run() function periodically to check if the work should end early.

isDone()

int isDone()

The isDone() function is a convenience wrapper around getState() that locks for thread safety and returns true if the job state is currently ROSE_MESH_JOB_DONE.

isIdle()

int isIdle()

The isIdle() function is a convenience wrapper around getState() that locks for thread safety and returns true if the job state is currently ROSE_MESH_JOB_IDLE.

lock()

void lock();

The lock() function acquires a mutex to allow safe access to job data across threads.

resetState()

void resetState();

The resetState() function resets the job state and result code to their initial values. The job state is set to ROSE_MESH_JOB_IDLE and the result code is set to zero. This is useful if you wish to run a job again.

run()

virtual void run() = 0;

The run() function is called by the job manager to execute the job. This will be called from a worker thread, and represents the actual job to be run. This function must be overridden by a subtype.

setResult()

void setResult(int val)

The setResult() function is used within run() to record a result value before returning. Call this function within a lock/unlock block for thread safety.

Zero should be used to indicate no result, such as not run or possibly canceled. Negative indicates error, and positive is success. Specific numeric values can be determined by the job.

setState()

void setState(int val);

The setState() function changes the state value recorded by the job. This is for internal use and should not be called by application code.

unlock()

void unlock();

The unlock() function releases a mutex to allow safe access to job data across threads.