xbmc/utils/Job.h

   1 /*
   2  *  Copyright (C) 2005-2018 Team Kodi
   3  *  This file is part of Kodi - https://kodi.tv
   4  *
   5  *  SPDX-License-Identifier: GPL-2.0-or-later
   6  *  See LICENSES/README.md for more information.
   7  */
   8
   9 #pragma once
  10
  11 class CJob;
  12
  13 #include <stddef.h>
  14
  15 #define kJobTypeMediaFlags  "mediaflags"
  16 #define kJobTypeCacheImage  "cacheimage"
  17 #define kJobTypeDDSCompress "ddscompress"
  18
  19 /*!
  20  \ingroup jobs
  21  \brief Callback interface for asynchronous jobs.
  22
  23  Used by clients of the CJobManager to receive progress, abort and completion notification of jobs.
  24  Clients of small jobs wishing to perform actions on job completion or abort should implement the
  25  IJobCallback::OnJobComplete() and/or IJobCallback::OnJobAbort() function.  Clients of larger jobs
  26  may choose to implement the IJobCallback::OnJobProgress() function in order to be kept informed of
  27  progress.
  28
  29  \sa CJobManager and CJob
  30  */
  31 class IJobCallback
  32 {
  33 public:
  34   /*!
  35    \brief Destructor for job call back objects.
  36
  37    \sa CJobManager and CJob
  38    */
  39   virtual ~IJobCallback() = default;
  40
  41   /*!
  42    \brief The callback used when a job completes.
  43
  44    OnJobComplete is called at the completion of the job's DoWork() function, and is used
  45    to return information to the caller on the result of the job.  On returning form this function
  46    the CJobManager will destroy this job.
  47
  48    \param jobID the unique id of the job (as retrieved from CJobManager::AddJob)
  49    \param success the result from the DoWork call
  50    \param job the job that has been processed.  The job will be destroyed after this function returns
  51    \sa CJobManager and CJob
  52    */
  53   virtual void OnJobComplete(unsigned int jobID, bool success, CJob *job)=0;
  54
  55   /*!
  56    \brief An optional callback function used when a job will be aborted.
  57
  58    OnJobAbort is called whenever a job gets aborted before or while being executed.
  59    Job's DoWork method will not be called, OnJobComplete will not be called.  The job instance will
  60    be destroyed by the caller after calling this function.
  61
  62    \param jobID the unique id of the job (as retrieved from CJobManager::AddJob)
  63    \param job the job that has been aborted.
  64    \sa CJobManager and CJob
  65    */
  66   virtual void OnJobAbort(unsigned int jobID, CJob* job) {}
  67
  68   /*!
  69    \brief An optional callback function that a job may call while processing.
  70
  71    OnJobProgress may be called periodically by a job during it's DoWork() function.  It is used
  72    by the job to report on progress.
  73
  74    \param jobID the unique id of the job (as retrieved from CJobManager::AddJob)
  75    \param progress the current progress of the job, out of total.
  76    \param total the total amount of work to be processed.
  77    \param job the job that has been processed.
  78    \sa CJobManager and CJob
  79    */
  80   virtual void OnJobProgress(unsigned int jobID,
  81                              unsigned int progress,
  82                              unsigned int total,
  83                              const CJob* job)
  84   {
  85   }
  86 };
  87
  88 class CJobManager;
  89
  90 /*!
  91  \ingroup jobs
  92  \brief Base class for jobs that are executed asynchronously.
  93
  94  Clients of the CJobManager should subclass CJob and provide the DoWork() function. Data should be
  95  passed to the job on creation, and any data sharing between the job and the client should be kept to within
  96  the callback functions if possible, and guarded with critical sections as appropriate.
  97
  98  Jobs typically fall into two groups: small jobs that perform a single function, and larger jobs that perform a
  99  sequence of functions.  Clients with small jobs should implement the IJobCallback::OnJobComplete() callback to receive results.
 100  Clients with larger jobs may wish to implement both the IJobCallback::OnJobComplete() and IJobCallback::OnJobProgress()
 101  callbacks to receive updates.  Jobs may be cancelled at any point by the client via CJobManager::CancelJob(), however
 102  effort should be taken to ensure that any callbacks and cancellation is suitably guarded against simultaneous thread access.
 103
 104  Handling cancellation of jobs within the OnJobProgress callback is a threadsafe operation, as all execution is
 105  then in the Job thread.
 106
 107  \sa CJobManager and IJobCallback
 108  */
 109 class CJob
 110 {
 111 public:
 112   /*!
 113    \brief Priority levels for jobs, specified by clients when adding jobs to the CJobManager.
 114    \sa CJobManager
 115    */
 116   enum PRIORITY {
 117     PRIORITY_LOW_PAUSABLE = 0,
 118     PRIORITY_LOW,
 119     PRIORITY_NORMAL,
 120     PRIORITY_HIGH,
 121     PRIORITY_DEDICATED, // will create a new worker if no worker is available at queue time
 122   };
 123   CJob() { m_callback = NULL; }
 124
 125   /*!
 126    \brief Destructor for job objects.
 127
 128    Jobs are destroyed by the CJobManager after the OnJobComplete() or OnJobAbort() callback is
 129    complete.  CJob subclasses should therefore supply a virtual destructor to cleanup any memory
 130    allocated by complete or cancelled jobs.
 131
 132    \sa CJobManager
 133    */
 134   virtual ~CJob() = default;
 135
 136   /*!
 137    \brief Main workhorse function of CJob instances
 138
 139    All CJob subclasses must implement this function, performing all processing.  Once this function
 140    is complete, the OnJobComplete() callback is called, and the job is then destroyed.
 141
 142    \sa CJobManager, IJobCallback::OnJobComplete()
 143    */
 144   virtual bool DoWork() = 0;  // function to do the work
 145
 146   /*!
 147    \brief Function that returns the type of job.
 148
 149    CJob subclasses may optionally implement this function to specify the type of job.
 150    This is useful for the CJobManager::AddLIFOJob() routine, which preempts similar jobs
 151    with the new job.
 152
 153    \return a unique character string describing the job.
 154    \sa CJobManager
 155    */
 156   virtual const char* GetType() const { return ""; }
 157
 158   virtual bool operator==(const CJob* job) const
 159   {
 160     return false;
 161   }
 162
 163   /*!
 164    \brief Function for longer jobs to report progress and check whether they have been cancelled.
 165
 166    Jobs that contain loops that may take time should check this routine each iteration of the loop,
 167    both to (optionally) report progress, and to check for cancellation.
 168
 169    \param progress the amount of the job performed, out of total.
 170    \param total the total amount of processing to be performed
 171    \return if true, the job has been asked to cancel.
 172
 173    \sa IJobCallback::OnJobProgress()
 174    */
 175   virtual bool ShouldCancel(unsigned int progress, unsigned int total) const;
 176 private:
 177   friend class CJobManager;
 178   CJobManager *m_callback;
 179 };