code.vuplus.com Git - vuplus_xbmc/blob - xbmc/utils/Job.h

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