src/base/AsyncJob.h

   1 /*
   2  * Copyright (C) 1996-2014 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 #ifndef SQUID_ASYNC_JOB_H
  10 #define SQUID_ASYNC_JOB_H
  11
  12 #include "base/AsyncCall.h"
  13 #include "base/InstanceId.h"
  14
  15 template <class Cbc>
  16 class CbcPointer;
  17
  18 /**
  19  \defgroup AsyncJobAPI Async-Jobs API
  20  \par
  21  * AsyncJob is an API and a base for a class that implements a stand-alone
  22  * "job", "task", or "logical processing thread" which receives asynchronous
  23  * calls.
  24  */
  25
  26 // See AsyncJobs.dox for details.
  27
  28 /// \ingroup AsyncJobAPI
  29 /// Base class for all asynchronous jobs
  30 class AsyncJob
  31 {
  32 public:
  33     typedef CbcPointer<AsyncJob> Pointer;
  34
  35 public:
  36     AsyncJob(const char *aTypeName);
  37     virtual ~AsyncJob();
  38
  39     virtual void *toCbdata() = 0;
  40
  41     /// starts a freshly created job (i.e., makes the job asynchronous)
  42     static Pointer Start(AsyncJob *job);
  43
  44 protected:
  45     // XXX: temporary method to replace "delete this" in jobs-in-transition.
  46     // Will be replaced with calls to mustStop() when transition is complete.
  47     void deleteThis(const char *aReason);
  48
  49     // force done() for a reason but continue with the current method
  50     void mustStop(const char *aReason);
  51
  52     bool done() const; ///< the job is destroyed in callEnd() when done()
  53
  54     virtual void start(); ///< called by AsyncStart; do not call directly
  55     virtual bool doneAll() const; ///< whether positive goal has been reached
  56     virtual void swanSong() {}; ///< internal cleanup; do not call directly
  57     virtual const char *status() const; ///< for debugging, starts with space
  58
  59 public:
  60     bool canBeCalled(AsyncCall &call) const; ///< whether we can be called
  61     void callStart(AsyncCall &call); ///< called just before the called method
  62     /// called right after the called job method
  63     virtual void callEnd(); ///< called right after the called job method
  64     /// called when the job throws during an async call
  65     virtual void callException(const std::exception &e);
  66
  67 protected:
  68     const char *stopReason; ///< reason for forcing done() to be true
  69     const char *typeName; ///< kid (leaf) class name, for debugging
  70     AsyncCall::Pointer inCall; ///< the asynchronous call being handled, if any
  71     const InstanceId<AsyncJob> id; ///< job identifier
  72 };
  73
  74 #endif /* SQUID_ASYNC_JOB_H */
  75