]>
git.ipfire.org Git - thirdparty/squid.git/blob - src/base/AsyncCall.h
2 * Copyright (C) 1996-2014 The Squid Software Foundation and contributors
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.
9 #ifndef SQUID_ASYNCCALL_H
10 #define SQUID_ASYNCCALL_H
12 #include "base/InstanceId.h"
17 \defgroup AsynCallsAPI Async-Calls API
19 * A call is asynchronous if the caller proceeds after the call is made,
20 * and the callee receives the call during the next main loop iteration.
21 * Asynchronous calls help avoid nasty call-me-when-I-call-you loops
22 * that humans often have trouble understanding or implementing correctly.
24 * Asynchronous calls are currently implemented via Squid events. The call
25 * event stores the pointer to the callback function and cbdata-protected
26 * callback data. To call a method of an object, the method is wrapped
27 * in a method-specific, static callback function and the pointer to the
28 * object is passed to the wrapper. For the method call to be safe, the
29 * class must be cbdata-enabled.
31 * You do not have to use the macros below to make or receive asynchronous
32 * method calls, but they give you a uniform interface and handy call
40 \todo add unique call IDs
41 \todo CBDATA_CLASS2 kids
42 \ingroup AsyncCallsAPI
44 class AsyncCall
: public RefCountable
47 typedef RefCount
<AsyncCall
> Pointer
;
48 friend class AsyncCallQueue
;
50 AsyncCall(int aDebugSection
, int aDebugLevel
, const char *aName
);
53 void make(); // fire if we can; handles general call debugging
55 // can be called from canFire() for debugging; always returns false
56 bool cancel(const char *reason
);
58 bool canceled() { return isCanceled
!= NULL
; }
60 virtual CallDialer
*getDialer() = 0;
62 void print(std::ostream
&os
);
64 /// remove us from the queue; we are head unless we are queued after prev
65 void dequeue(AsyncCall::Pointer
&head
, AsyncCall::Pointer
&prev
);
67 void setNext(AsyncCall::Pointer aNext
) {
71 AsyncCall::Pointer
&Next() {
76 const char *const name
;
77 const int debugSection
;
79 const InstanceId
<AsyncCall
> id
;
82 virtual bool canFire();
84 virtual void fire() = 0;
86 AsyncCall::Pointer theNext
; // used exclusively by AsyncCallQueue
89 const char *isCanceled
; // set to the cancelation reason by cancel()
91 // not implemented to prevent nil calls from being passed around and unknowingly scheduled, for now.
93 AsyncCall(const AsyncCall
&);
97 std::ostream
&operator <<(std::ostream
&os
, AsyncCall
&call
)
104 \ingroup AsyncCallAPI
105 * Interface for all async call dialers
111 virtual ~CallDialer() {}
113 // TODO: Add these for clarity when CommCbFunPtrCallT is gone
114 //virtual bool canDial(AsyncCall &call) = 0;
115 //virtual void dial(AsyncCall &call) = 0;
117 virtual void print(std::ostream
&os
) const = 0;
121 \ingroup AsyncCallAPI
122 * This template implements an AsyncCall using a specified Dialer class
124 template <class Dialer
>
125 class AsyncCallT
: public AsyncCall
128 AsyncCallT(int aDebugSection
, int aDebugLevel
, const char *aName
,
129 const Dialer
&aDialer
): AsyncCall(aDebugSection
, aDebugLevel
, aName
),
132 AsyncCallT(const AsyncCallT
<Dialer
> &o
):
133 AsyncCall(o
.debugSection
, o
.debugLevel
, o
.name
),
138 CallDialer
*getDialer() { return &dialer
; }
141 virtual bool canFire() {
142 return AsyncCall::canFire() &&
143 dialer
.canDial(*this);
145 virtual void fire() { dialer
.dial(*this); }
150 AsyncCallT
& operator=(const AsyncCallT
&); // not defined. call assignments not permitted.
153 template <class Dialer
>
156 asyncCall(int aDebugSection
, int aDebugLevel
, const char *aName
,
157 const Dialer
&aDialer
)
159 return new AsyncCallT
<Dialer
>(aDebugSection
, aDebugLevel
, aName
, aDialer
);
162 /** Call scheduling helper. Use ScheduleCallHere if you can. */
163 bool ScheduleCall(const char *fileName
, int fileLine
, AsyncCall::Pointer
&call
);
165 /** Call scheduling helper. */
166 #define ScheduleCallHere(call) ScheduleCall(__FILE__, __LINE__, (call))
168 #endif /* SQUID_ASYNCCALL_H */