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