From: Amos Jeffries <squid3@treenet.co.nz>
Date: Thu, 7 Oct 2010 07:53:45 +0000 (+1300)
Subject: Author: Alex Rousskov <rousskov@measurement-factory.com>
X-Git-Tag: take1~194
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=3cb19943bf9f142572737e679b7170874e5a0032;p=thirdparty%2Fsquid.git

Author: Alex Rousskov <rousskov@measurement-factory.com>
Author: Amos Jeffries <squid3@treenet.co.nz>
API for subscribing AsyncCall handlers to event producers

This API allows AsyncCall handlers to be subscribed for receiving multiple
event callbacks from producer/factory classes.

Intended use-cases include the main port listeners which are started once.
Run for a long time. And over their lifetime need to generate multiple
calls to any one of several handlers without having specific type details
hard-coded about the calls they are spawning.
 ie they cannot use "new X(y,z)" because they are not aware of y and z.
    Nor can one AsyncCall be scheduled and fired multiple times.

Other use-cases already sighted are UDP readers and event timers.
---

diff --git a/src/base/Makefile.am b/src/base/Makefile.am
index 72c7f83089..b50866e0c9 100644
--- a/src/base/Makefile.am
+++ b/src/base/Makefile.am
@@ -14,5 +14,6 @@ libbase_la_SOURCES = \
 	AsyncCallQueue.h \
 	CbcPointer.h \
 	InstanceId.h \
+	Subscription.h \
 	TextException.cc \
 	TextException.h
diff --git a/src/base/Subscription.h b/src/base/Subscription.h
new file mode 100644
index 0000000000..ec9cc517f7
--- /dev/null
+++ b/src/base/Subscription.h
@@ -0,0 +1,51 @@
+#ifndef _SQUID_BASE_SUBSCRIPTION_H
+#define _SQUID_BASE_SUBSCRIPTION_H
+
+#include "base/AsyncCall.h"
+
+/** API for creating a series of AsyncCalls.
+ * This is necessary because the same AsyncCall callback must not be
+ * fired multiple times.
+ *
+ * The call producer needs to accept and store a Subscription::Pointer.
+ * It also should provide some mechanism for adding/removing/changing
+ * the stored Subscription::Pointer.
+ *
+ * The callback() method of Subscription::Pointer will spawn AsyncCall
+ * to be filled out and scheduled as needed.
+ */
+class Subscription: public RefCountable
+{
+public:
+    typedef RefCount<Subscription> Pointer;
+
+    /** returns a call object to be used for the next call back.
+     * Child implementations must ensure the Call pointer produced
+     * is not NULL.
+     */
+    virtual AsyncCall::Pointer callback() const = 0;
+};
+
+/** Implements Subscription API using Call's copy constructor.
+ *
+ * The subscriber creates one of these using a specific callback
+ * type and instance. The subscription object is then passed to a
+ * producer/factory which will use this API to generate calls.
+ * A subscription may be passed to multiple producers.
+ *
+ * Call_ must have a copy constructor.
+ * A pointer to Call_ must be convertable to AsyncCall::Pointer
+ */
+template<class Call_>
+class CallSubscription: public Subscription
+{
+public:
+    /// Must be passed an object. nil pointers are not permitted.
+    explicit CallSubscription(const RefCount<Call_> &aCall) : call(aCall) { assert(aCall != NULL); }
+    virtual AsyncCall::Pointer callback() const { return new Call_(call); }
+
+private:
+    const RefCount<Call_> call; ///< gets copied to create callback calls
+};
+
+#endif /* _SQUID_BASE_SUBSCRIPTION_H */