]>
git.ipfire.org Git - thirdparty/squid.git/blob - src/base/AsyncCall.h
2 * Copyright (C) 1996-2020 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/CodeContext.h"
13 #include "base/InstanceId.h"
18 \defgroup AsynCallsAPI Async-Calls API
20 * A call is asynchronous if the caller proceeds after the call is made,
21 * and the callee receives the call during the next main loop iteration.
22 * Asynchronous calls help avoid nasty call-me-when-I-call-you loops
23 * that humans often have trouble understanding or implementing correctly.
25 * Asynchronous calls are currently implemented via Squid events. The call
26 * event stores the pointer to the callback function and cbdata-protected
27 * callback data. To call a method of an object, the method is wrapped
28 * in a method-specific, static callback function and the pointer to the
29 * object is passed to the wrapper. For the method call to be safe, the
30 * class must be cbdata-enabled.
32 * You do not have to use the macros below to make or receive asynchronous
33 * method calls, but they give you a uniform interface and handy call
41 \todo add unique call IDs
42 \todo CBDATA_CLASS kids
43 \ingroup AsyncCallsAPI
45 class AsyncCall
: public RefCountable
48 typedef RefCount
<AsyncCall
> Pointer
;
49 friend class AsyncCallQueue
;
51 AsyncCall(int aDebugSection
, int aDebugLevel
, const char *aName
);
54 void make(); // fire if we can; handles general call debugging
56 // can be called from canFire() for debugging; always returns false
57 bool cancel(const char *reason
);
59 bool canceled() { return isCanceled
!= NULL
; }
61 virtual CallDialer
*getDialer() = 0;
63 void print(std::ostream
&os
);
65 /// remove us from the queue; we are head unless we are queued after prev
66 void dequeue(AsyncCall::Pointer
&head
, AsyncCall::Pointer
&prev
);
68 void setNext(AsyncCall::Pointer aNext
) {
72 AsyncCall::Pointer
&Next() {
77 const char *const name
;
79 /// what the callee is expected to work on
80 CodeContext::Pointer codeContext
;
82 const int debugSection
;
84 const InstanceId
<AsyncCall
> id
;
87 virtual bool canFire();
89 virtual void fire() = 0;
91 AsyncCall::Pointer theNext
; // used exclusively by AsyncCallQueue
94 const char *isCanceled
; // set to the cancelation reason by cancel()
96 // not implemented to prevent nil calls from being passed around and unknowingly scheduled, for now.
98 AsyncCall(const AsyncCall
&);
102 std::ostream
&operator <<(std::ostream
&os
, AsyncCall
&call
)
109 \ingroup AsyncCallAPI
110 * Interface for all async call dialers
116 virtual ~CallDialer() {}
118 // TODO: Add these for clarity when CommCbFunPtrCallT is gone
119 //virtual bool canDial(AsyncCall &call) = 0;
120 //virtual void dial(AsyncCall &call) = 0;
122 virtual void print(std::ostream
&os
) const = 0;
126 \ingroup AsyncCallAPI
127 * This template implements an AsyncCall using a specified Dialer class
129 template <class Dialer
>
130 class AsyncCallT
: public AsyncCall
133 AsyncCallT(int aDebugSection
, int aDebugLevel
, const char *aName
,
134 const Dialer
&aDialer
): AsyncCall(aDebugSection
, aDebugLevel
, aName
),
137 AsyncCallT(const AsyncCallT
<Dialer
> &o
):
138 AsyncCall(o
.debugSection
, o
.debugLevel
, o
.name
),
143 CallDialer
*getDialer() { return &dialer
; }
146 virtual bool canFire() {
147 return AsyncCall::canFire() &&
148 dialer
.canDial(*this);
150 virtual void fire() { dialer
.dial(*this); }
155 AsyncCallT
& operator=(const AsyncCallT
&); // not defined. call assignments not permitted.
158 template <class Dialer
>
161 asyncCall(int aDebugSection
, int aDebugLevel
, const char *aName
,
162 const Dialer
&aDialer
)
164 return new AsyncCallT
<Dialer
>(aDebugSection
, aDebugLevel
, aName
, aDialer
);
167 /** Call scheduling helper. Use ScheduleCallHere if you can. */
168 bool ScheduleCall(const char *fileName
, int fileLine
, AsyncCall::Pointer
&call
);
170 /** Call scheduling helper. */
171 #define ScheduleCallHere(call) ScheduleCall(__FILE__, __LINE__, (call))
173 #endif /* SQUID_ASYNCCALL_H */