X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=PPI%2FEvents.hh;h=39e9d486cff61a5d86b90aada56961fd201703b6;hb=d5a72d0b3f6fee56dba6de1c54cafb448ebe3457;hp=fffd59e1bb7846a7f9236af88a443c01822ccafe;hpb=7465ea4f6d3d54622bd783106cf8b60d5f133343;p=senf.git

diff --git a/PPI/Events.hh b/PPI/Events.hh
index fffd59e..39e9d48 100644
--- a/PPI/Events.hh
+++ b/PPI/Events.hh
@@ -1,6 +1,8 @@
-// Copyright (C) 2007 
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
+// $Id$
+//
+// Copyright (C) 2007
+// Fraunhofer Institute for Open Communication Systems (FOKUS)
+// Competence Center NETwork research (NET), St. Augustin, GERMANY
 //     Stefan Bund <g0dil@berlios.de>
 //
 // This program is free software; you can redistribute it and/or modify
@@ -21,11 +23,12 @@
 /** \file
     \brief Events public header */
 
-#ifndef HH_Events_
-#define HH_Events_ 1
+#ifndef HH_SENF_PPI_Events_
+#define HH_SENF_PPI_Events_ 1
 
 // Custom includes
-#include <boost/date_time/posix_time/posix_time_types.hpp>
+#include <vector>
+#include "../Scheduler/ClockService.hh"
 #include "predecl.hh"
 
 //#include "Events.mpp"
@@ -33,6 +36,19 @@
 
 namespace senf {
 namespace ppi {
+    
+    /** \defgroup event_group Events
+
+        Events provide notification of events outside the PPI framework: I/O activity, Timers
+        etc. Events are very important since they drive the PPI: Without events, nothing will
+        happen.
+
+        \section event_impl Implementing Events
+
+        All events are derived from EventImplementation which is based on EventDescriptor.
+        \see EventImplementation \n
+            \ref ppi_events        
+     */
 
     // Implementation: The concrete EventDescriptor implementation will need to set things up so
     // some callback (within the EventDescriptor implementation) will be called when the event
@@ -42,10 +58,11 @@ namespace ppi {
     // 'callback()' will access the EventBinding wrapper to find the user-callback to signal. It
     // will do any needed internal processing, call that user callback and clean up afterwards.
 
-    /** \brief Generic event interface baseclass
+    /** \brief Generic event interface base-class
+
+        The EventDescriptor base-class provides an interface to control events.
 
-        The EventDescriptor baseclass provides an interface to manipulate events in a generic
-        way. This allows to register events or to temporarily disable event processing.
+        \see \ref ppi_events
      */ 
     class EventDescriptor
     {
@@ -67,35 +84,90 @@ namespace ppi {
         void notifyThrottle();
         void notifyUnthrottle();
 
+        void registerRoute(ForwardingRoute & route);
+
         bool enabled_;
+        bool throttled_;
+
+        typedef std::vector<ForwardingRoute*> Routes;
+        Routes routes_;
 
         friend class ForwardingRoute;
     };
     
+    /** \brief Internal: Callback forwarders
+     */
     template <class EventType, class Self>
     class EventImplementationHelper
     {
     protected:
         typedef typename detail::EventArgType<EventType>::type EventArg;
 
-        void callback(EventArg event, boost::posix_time::ptime time);
-        void callback(EventArg event);
+        void callback(EventArg event, ClockService::clock_type time);
+                                        ///< Forward event to user callback
+                                        /**< \param[in] event Event argument to pass to the user
+                                             callback
+                                             \param[in] time Expected time of the event */
+        void callback(EventArg event);  ///< Forward event to user callback
+                                        /**< \param[in] event Event argument to pass to the user
+                                             callback. */
 
     private:
         detail::EventBinding<EventType> & binding();
     };
     
+#ifndef DOXYGEN
+
     template <class Self>
     class EventImplementationHelper<void,Self>
     {
     protected:
-        void callback(boost::posix_time::ptime time);
+        void callback(ClockService::clock_type time);
         void callback();
 
     private:
         detail::EventBinding<void> & binding();
     };
 
+#endif
+
+    /** \brief Event implementation base class
+
+        EventImplementation provides the base-class for all Event implementations. 
+        \code
+        class SomeEvent : public EventImplementation<SomeEventArg>
+        {
+        public:
+            SomeEvent() {}
+
+        private:
+            virtual void v_enable() {
+                // register cb() to be called when the event occurs
+            }
+
+            virtual void v_disable() {
+                // unregister cb()
+            }
+
+            void cb() {
+                // Build event argument
+                SomeEventArg arg (...); 
+                // Call the event callback
+                callback(arg);
+            }
+        };
+        \endcode
+
+        Every event needs to implement v_enable() and v_disable(). v_enable() should register some
+        member (in the example \c cb() ) to be called whenever the event occurs, while v_disable()
+        should unregister it.
+
+        The \a EventType argument to EventImplementation defines the type of argument passed to the
+        user callback. It defaults to \c void. . This user callback is called from within the
+        registered member (e.g. \c cb() ) by calling the inherited callback() member. This member
+        takes an \a EventType reference as argument which will be forwarded to the user callback. If
+        available, you should also provide the \e expected event time as a second argument.
+     */
     template <class EventType>
     class EventImplementation
         : public EventDescriptor, 
@@ -105,6 +177,9 @@ namespace ppi {
         typedef EventType Event;
         typedef typename detail::EventArgType<EventType>::type EventArg;
 
+        module::Module & module() const; ///< Module in which the event is registered
+        EventManager & manager() const; ///< EventManager of the event
+        
     protected:
         EventImplementation();