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