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 72c7f830897bf671e809a89cf8975b203d55360f..b50866e0c9c301d53040b036e82afa659a80666d 100644 (file)
--- 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 (file)
index 0000000..ec9cc51
--- /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 */