src/AsyncFramework/JobBase.h

   1 /***************************************************************************
   2  *   Copyright (C) 2009-2010, 2012 by Stefan Fuhrmann                      *
   3  *   stefanfuhrmann@alice-dsl.de                                           *
   4  *                                                                         *
   5  *   This program is free software; you can redistribute it and/or modify  *
   6  *   it under the terms of the GNU General Public License as published by  *
   7  *   the Free Software Foundation; either version 2 of the License, or     *
   8  *   (at your option) any later version.                                   *
   9  *                                                                         *
  10  *   This program is distributed in the hope that it will be useful,       *
  11  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  12  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  13  *   GNU General Public License for more details.                          *
  14  *                                                                         *
  15  *   You should have received a copy of the GNU General Public License     *
  16  *   along with this program; if not, write to the                         *
  17  *   Free Software Foundation, Inc.,                                       *
  18  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  19  ***************************************************************************/
  20
  21 #pragma once
  22
  23 #include "IJob.h"
  24 #include "WaitableEvent.h"
  25
  26 namespace async
  27 {
  28
  29 /**
  30  * Common base implementation of \ref IJob.
  31  * All your job class deriving from this one
  32  * has to do is to implement \ref InternalExecute.
  33  */
  34
  35 class CJobBase : public IJob
  36 {
  37 private:
  38
  39     /// waitable event. Will be set after \ref Execute() finished.
  40
  41     COneShotEvent executionDone;
  42
  43     /// waitable event. Will be set when the job can be deleted.
  44
  45     COneShotEvent deletable;
  46
  47     /// TRUE until Execute() is called
  48
  49     volatile LONG waiting;
  50
  51     /// if set, we should not run at all or at least try to terminate asap
  52
  53     volatile LONG terminated;
  54
  55     /// if set, \ref finished will not be signalled unless
  56     /// \ref Execute is called from the scheduler.
  57
  58     volatile LONG scheduled;
  59
  60     /// For now, update the internal @a scheduled flag only.
  61
  62     void OnSchedule (CJobScheduler* scheduler);
  63
  64     /// For now, update the internal @a scheduled flag only.
  65
  66     void OnUnSchedule (CJobScheduler* scheduler);
  67
  68 protected:
  69
  70     /// base class is not intended for creation
  71
  72     CJobBase(void);
  73
  74     /// implement this in your job class
  75
  76     virtual void InternalExecute() = 0;
  77
  78     /// asserts that the job is deletable
  79
  80     virtual ~CJobBase(void);
  81
  82 public:
  83
  84     /// call this to put the job into the scheduler
  85
  86     virtual void Schedule (bool transferOwnership, CJobScheduler* scheduler) override;
  87
  88     // will be called by job execution thread
  89
  90     virtual void Execute() override;
  91
  92     /// may be called by other (observing) threads
  93
  94     virtual Status GetStatus() const override;
  95
  96     /// wait until job execution finished.
  97     /// If @ref inlineExecution is set, the job will be
  98     /// executed in the current thread if it is still waiting.
  99
 100     virtual void WaitUntilDone (bool inlineExecution = false) override;
 101
 102     /// returns false in case of a timeout
 103
 104     virtual bool WaitUntilDoneOrTimeout(DWORD milliSeconds);
 105
 106     /// request early termination.
 107     /// Will even prevent execution if not yet started.
 108     /// Execution will still finish 'successfully', i.e
 109     /// results in \ref IJob::done state.
 110
 111     virtual void Terminate();
 112
 113     /// \returns true if termination has been requested.
 114     /// Please note that execution may still be ongoing
 115     /// despite the termination request.
 116
 117     virtual bool HasBeenTerminated() const;
 118
 119     /// Call @a delete on this job as soon as it is safe to do so.
 120
 121     virtual void Delete (bool terminate);
 122
 123 };
 124
 125 }