Kodi Documentation 22.0
Kodi is an open source media player and entertainment hub.
Loading...
Searching...
No Matches
CJob Class Referenceabstract

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

#include <Job.h>

Inheritance diagram for CJob:
CAutorunMediaJob CDetectDisc CDirectoryJob CGUIMultiImage::CMultiImageJob CGetInfoJob CGetSongInfoJob CImageLoader CLambdaJob< F > CMACDiscoveryJob CMusicLibraryJob CProgressJob CRecentlyAddedJob CSetUserratingJob CSubtitlesJob CSysInfoJob CTextureCacheJob CTextureUseCountJob CThumbnailWriter CVideoLibraryJob CWeatherJob DummyJob KODI::CDRIP::CCDDARipJob MUSIC_UTILS::CSetArtJob MUSIC_UTILS::CSetSongRatingJob PERIPHERALS::CPeripheralCecAdapterReopenJob PVR::CPVREventLogJob ReallyDumbJob

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 ()
 
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 operator== (const CJob *job) const
 
virtual bool ShouldCancel (unsigned int progress, unsigned int total) const
 Function for longer jobs to report progress and check whether they have been cancelled.
 

Friends

class CJobManager
 

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

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 ( )
inline

◆ ~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()

◆ 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::AddLIFOJob() routine, which preempts similar jobs with the new job.

Returns
a unique character string describing the job.
See also
CJobManager

Reimplemented in CDirectoryJob, 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.

◆ operator==()

◆ 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
progressthe amount of the job performed, out of total.
totalthe total amount of processing to be performed
Returns
if true, the job has been asked to cancel.
See also
IJobCallback::OnJobProgress()

Reimplemented in CProgressJob.

Friends And Related Symbol Documentation

◆ CJobManager

friend class CJobManager
friend

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