src/base/AsyncCall.h

   1 /*
   2  * $Id$
   3  */
   4
   5 #ifndef SQUID_ASYNCCALL_H
   6 #define SQUID_ASYNCCALL_H
   7
   8 #include "base/InstanceId.h"
   9 #include "event.h"
  10 #include "RefCount.h"
  11
  12 /**
  13  \defgroup AsynCallsAPI Async-Calls API
  14  \par
  15  * A call is asynchronous if the caller proceeds after the call is made,
  16  * and the callee receives the call during the next main loop iteration.
  17  * Asynchronous calls help avoid nasty call-me-when-I-call-you loops
  18  * that humans often have trouble understanding or implementing correctly.
  19  \par
  20  * Asynchronous calls are currently implemented via Squid events. The call
  21  * event stores the pointer to the callback function and cbdata-protected
  22  * callback data. To call a method of an object, the method is wrapped
  23  * in a method-specific, static callback function and the pointer to the
  24  * object is passed to the wrapper. For the method call to be safe, the
  25  * class must be cbdata-enabled.
  26  \par
  27  * You do not have to use the macros below to make or receive asynchronous
  28  * method calls, but they give you a uniform interface and handy call
  29  * debugging.
  30  */
  31
  32 class CallDialer;
  33 class AsyncCallQueue;
  34
  35 /**
  36  \todo add unique call IDs
  37  \todo CBDATA_CLASS2 kids
  38  \ingroup AsyncCallsAPI
  39  */
  40 class AsyncCall: public RefCountable
  41 {
  42 public:
  43     typedef RefCount <AsyncCall> Pointer;
  44     friend class AsyncCallQueue;
  45
  46     AsyncCall(int aDebugSection, int aDebugLevel, const char *aName);
  47     virtual ~AsyncCall();
  48
  49     void make(); // fire if we can; handles general call debugging
  50
  51     // can be called from canFire() for debugging; always returns false
  52     bool cancel(const char *reason);
  53
  54     bool canceled() { return isCanceled != NULL; }
  55
  56     virtual CallDialer *getDialer() = 0;
  57
  58     void print(std::ostream &os);
  59
  60     /// remove us from the queue; we are head unless we are queued after prev
  61     void dequeue(AsyncCall::Pointer &head, AsyncCall::Pointer &prev);
  62
  63     void setNext(AsyncCall::Pointer aNext) {
  64         theNext = aNext;
  65     }
  66
  67     AsyncCall::Pointer &Next() {
  68         return theNext;
  69     }
  70
  71 public:
  72     const char *const name;
  73     const int debugSection;
  74     const int debugLevel;
  75     const InstanceId<AsyncCall> id;
  76
  77 protected:
  78     virtual bool canFire();
  79
  80     virtual void fire() = 0;
  81
  82     AsyncCall::Pointer theNext; // used exclusively by AsyncCallQueue
  83
  84 private:
  85     const char *isCanceled; // set to the cancelation reason by cancel()
  86
  87     // not implemented to prevent nil calls from being passed around and unknowingly scheduled, for now.
  88     AsyncCall();
  89     AsyncCall(const AsyncCall &);
  90 };
  91
  92 inline
  93 std::ostream &operator <<(std::ostream &os, AsyncCall &call)
  94 {
  95     call.print(os);
  96     return os;
  97 }
  98
  99 /**
 100  \ingroup AsyncCallAPI
 101  * Interface for all async call dialers
 102  */
 103 class CallDialer
 104 {
 105 public:
 106     CallDialer() {}
 107     virtual ~CallDialer() {}
 108
 109     // TODO: Add these for clarity when CommCbFunPtrCallT is gone
 110     //virtual bool canDial(AsyncCall &call) = 0;
 111     //virtual void dial(AsyncCall &call) = 0;
 112
 113     virtual void print(std::ostream &os) const = 0;
 114 };
 115
 116 /**
 117  \ingroup AsyncCallAPI
 118  * This template implements an AsyncCall using a specified Dialer class
 119  */
 120 template <class Dialer>
 121 class AsyncCallT: public AsyncCall
 122 {
 123 public:
 124     AsyncCallT(int aDebugSection, int aDebugLevel, const char *aName,
 125                const Dialer &aDialer): AsyncCall(aDebugSection, aDebugLevel, aName),
 126             dialer(aDialer) {}
 127
 128     AsyncCallT(const AsyncCallT<Dialer> &o):
 129             AsyncCall(o.debugSection, o.debugLevel, o.name),
 130             dialer(o.dialer) {}
 131
 132     ~AsyncCallT() {}
 133
 134     CallDialer *getDialer() { return &dialer; }
 135
 136 protected:
 137     virtual bool canFire() {
 138         return AsyncCall::canFire() &&
 139                dialer.canDial(*this);
 140     }
 141     virtual void fire() { dialer.dial(*this); }
 142
 143     Dialer dialer;
 144
 145 private:
 146     AsyncCallT & operator=(const AsyncCallT &); // not defined. call assignments not permitted.
 147 };
 148
 149 template <class Dialer>
 150 inline
 151 AsyncCall *
 152 asyncCall(int aDebugSection, int aDebugLevel, const char *aName,
 153           const Dialer &aDialer)
 154 {
 155     return new AsyncCallT<Dialer>(aDebugSection, aDebugLevel, aName, aDialer);
 156 }
 157
 158 /** Call scheduling helper. Use ScheduleCallHere if you can. */
 159 bool ScheduleCall(const char *fileName, int fileLine, AsyncCall::Pointer &call);
 160
 161 /** Call scheduling helper. */
 162 #define ScheduleCallHere(call) ScheduleCall(__FILE__, __LINE__, (call))
 163
 164 #endif /* SQUID_ASYNCCALL_H */