CJob Class Reference

Base class for jobs that are executed asynchronously. More...

#include <Job.h>

Inheritance diagram for CJob:

Public Types
enum	PRIORITY {   PRIORITY_LOW_PAUSABLE = 0 , PRIORITY_LOW , PRIORITY_NORMAL , PRIORITY_HIGH ,   PRIORITY_DEDICATED }
	Priority levels for jobs, specified by clients when adding jobs to the CJobManager. More...

Public Member Functions
	CJob ()=default
virtual	~CJob ()=default
	Destructor for job objects.
virtual bool	DoWork ()=0
	Main workhorse function of CJob instances.
virtual const char *	GetType () const
	Function that returns the type of job.
virtual bool	Equals (const CJob *job) const
	Function that compares this job instance with the given job instance.
void	SetProgressCallback (CJobManager *callback)
	Function to set a callback for jobs to report progress.
virtual bool	ShouldCancel (unsigned int progress, unsigned int total) const
	Function for longer jobs to report progress and check whether they have been cancelled.

Detailed Description

Base class for jobs that are executed asynchronously.

Clients of the CJobManager should subclass CJob and provide the DoWork() function. Data should be passed to the job on creation, and any data sharing between the job and the client should be kept to within the callback functions if possible, and guarded with critical sections as appropriate.

Jobs typically fall into two groups: small jobs that perform a single function, and larger jobs that perform a sequence of functions. Clients with small jobs should implement the IJobCallback::OnJobComplete() callback to receive results. Clients with larger jobs may wish to implement both the IJobCallback::OnJobComplete() and IJobCallback::OnJobProgress() callbacks to receive updates. Jobs may be cancelled at any point by the client via CJobManager::CancelJob(), however effort should be taken to ensure that any callbacks and cancellation is suitably guarded against simultaneous thread access.

Handling cancellation of jobs within the OnJobProgress callback is a threadsafe operation, as all execution is then in the Job thread.

See also

CJobManager and IJobCallback

Member Enumeration Documentation

PRIORITY

enum CJob::PRIORITY

Priority levels for jobs, specified by clients when adding jobs to the CJobManager.

See also

CJobManager

Enumerator
PRIORITY_LOW_PAUSABLE
PRIORITY_LOW
PRIORITY_NORMAL
PRIORITY_HIGH
PRIORITY_DEDICATED

Constructor & Destructor Documentation

CJob()

CJob::CJob ( )

default

~CJob()

virtual CJob::~CJob ( )

virtualdefault

Destructor for job objects.

Jobs are destroyed by the CJobManager after the OnJobComplete() or OnJobAbort() callback is complete. CJob subclasses should therefore supply a virtual destructor to cleanup any memory allocated by complete or cancelled jobs.

See also

CJobManager

Member Function Documentation

DoWork()

virtual bool CJob::DoWork ( )

pure virtual

Main workhorse function of CJob instances.

All CJob subclasses must implement this function, performing all processing. Once this function is complete, the OnJobComplete() callback is called, and the job is then destroyed.

See also

CJobManager, IJobCallback::OnJobComplete()

Implemented in ADDON::CRepositoryUpdateJob, CAutorunMediaJob, CDetectDisc, CFileOperationJob, CGetInfoJob, CGetSongInfoJob, CGUIMultiImage::CMultiImageJob, CImageLoader, CLambdaJob< F >, CMACDiscoveryJob, CMusicLibraryJob, CMusicLibraryProgressJob, CRecentlyAddedJob, CRefreshInfoJob, CSetUserratingJob, CSubtitlesJob, CSysInfoJob, CTextureCacheJob, CTextureUseCountJob, CThumbnailWriter, CVideoLibraryJob, CVideoLibraryProgressJob, CWeatherJob, DummyJob, KODI::CDRIP::CCDDARipJob, MUSIC_UTILS::CSetArtJob, MUSIC_UTILS::CSetSongRatingJob, PERIPHERALS::CPeripheralCecAdapterReopenJob, PVR::CPVREventLogJob, and ReallyDumbJob.

Equals()

virtual bool CJob::Equals ( const CJob * job ) const

inlinevirtual

Function that compares this job instance with the given job instance.

CJob subclasses may optionally implement this to provide customized comparison functionality. This is useful for the CJobManager::AddJob() routine, which preempts similar jobs with the new job.

Parameters

job	the job to compared with this CJob instance.

Returns

if true, the two jobs are equal.

See also

CJobManager::AddJob()

Reimplemented in CFileOperationJob, CLambdaJob< F >, CMusicLibraryCleaningJob, CMusicLibraryExportJob, CMusicLibraryImportJob, CMusicLibraryScanningJob, CSubtitlesJob, CTextureCacheJob, CTextureUseCountJob, CVideoLibraryCleaningJob, CVideoLibraryMarkWatchedJob, CVideoLibraryRefreshingJob, CVideoLibraryResetResumePointJob, CVideoLibraryScanningJob, and KODI::CDRIP::CCDDARipJob.

GetType()

virtual const char * CJob::GetType ( ) const

inlinevirtual

Function that returns the type of job.

CJob subclasses may optionally implement this function to specify the type of job. This is useful for the CJobManager::AddJob() routine, which preempts similar jobs with the new job.

Returns

a unique character string describing the job.

See also

CJobManager

Reimplemented in CFileOperationJob, CGUIMultiImage::CMultiImageJob, CMusicLibraryCleaningJob, CMusicLibraryExportJob, CMusicLibraryImportJob, CMusicLibraryJob, CMusicLibraryProgressJob, CMusicLibraryScanningJob, CProgressJob, CTextureCacheJob, CTextureUseCountJob, CVideoLibraryCleaningJob, CVideoLibraryJob, CVideoLibraryMarkWatchedJob, CVideoLibraryProgressJob, CVideoLibraryRefreshingJob, CVideoLibraryResetResumePointJob, CVideoLibraryScanningJob, KODI::CDRIP::CCDDARipJob, and PVR::CPVREventLogJob.

SetProgressCallback()

void CJob::SetProgressCallback ( CJobManager * callback )

inline

Function to set a callback for jobs to report progress.

Parameters

callback

the callback to use to report progress.

See also

IJobCallback::OnJobProgress()

ShouldCancel()

bool CJob::ShouldCancel ( unsigned int progress, unsigned int total ) const

virtual

Function for longer jobs to report progress and check whether they have been cancelled.

Jobs that contain loops that may take time should check this routine each iteration of the loop, both to (optionally) report progress, and to check for cancellation.

Parameters

progress	the amount of the job performed, out of total.
total	the total amount of processing to be performed

Returns

if true, the job has been asked to cancel.

See also

IJobCallback::OnJobProgress()

Reimplemented in CProgressJob.

---

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

• Job.h
• JobManager.cpp