4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
7 // Version 1.0 (the "License"); you may not use this file except in compliance
8 // with the License. You may obtain a copy of the License at
9 // http://senf.berlios.de/license.html
11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
12 // but modifies the Mozilla Public License Version 1.1.
13 // See the full license text for the amendments.
15 // Software distributed under the License is distributed on an "AS IS" basis,
16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
17 // for the specific language governing rights and limitations under the License.
19 // The Original Code is Fraunhofer FOKUS code.
21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
23 // All Rights Reserved.
26 // Stefan Bund <g0dil@berlios.de>
29 \brief Events public header */
31 #ifndef HH_SENF_PPI_Events_
32 #define HH_SENF_PPI_Events_ 1
36 #include <senf/Scheduler/ClockService.hh>
39 //#include "Events.mpp"
40 //-/////////////////////////////////////////////////////////////////////////////////////////////////
45 namespace detail { class EventBindingBase; }
47 /** \defgroup event_group Events
49 Events provide notification of events outside the PPI framework: I/O activity, Timers
50 etc. Events are very important since they drive the PPI: Without events, nothing will
53 \section event_impl Implementing Events
55 All events are derived from EventImplementation which is based on EventDescriptor.
56 \see EventImplementation \n
60 // Implementation: The concrete EventDescriptor implementation will need to set things up so
61 // some callback (within the EventDescriptor implementation) will be called when the event
62 // happens. This setup happens in 'v_enable()'. This internal handler sets up an EventType
63 // instance if needed and calls 'callback()'.
65 // 'callback()' will access the EventBinding wrapper to find the user-callback to signal. It
66 // will do any needed internal processing, call that user callback and clean up afterwards.
68 /** \brief Generic event interface base-class
70 The EventDescriptor base-class provides an interface to control events.
77 virtual ~EventDescriptor();
79 bool enabled() const; ///< Check, whether the event is currently enabled
80 void enabled(bool v); ///< Enable or disable the event
86 virtual void v_enable() = 0; ///< Called to enable the event delivery
87 virtual void v_disable() = 0; ///< Called to disable the event delivery
89 virtual bool v_isRegistered() = 0;
91 void notifyThrottle();
92 void notifyUnthrottle();
94 void registerRoute(ForwardingRoute & route);
95 void unregisterRoute(ForwardingRoute & route);
100 typedef std::vector<ForwardingRoute*> Routes;
103 detail::EventBindingBase * binding_;
105 friend class ForwardingRoute;
106 friend class detail::EventBindingBase;
109 /** \brief Internal: Callback forwarders
111 template <class EventType, class Self>
112 class EventImplementationHelper
115 typedef typename detail::EventArgType<EventType>::type EventArg;
117 void callback(EventArg event, ClockService::clock_type time);
118 ///< Forward event to user callback
119 /**< \param[in] event Event argument to pass to the user
121 \param[in] time Expected time of the event */
122 void callback(EventArg event); ///< Forward event to user callback
123 /**< \param[in] event Event argument to pass to the user
127 detail::EventBinding<EventType> & binding();
132 template <class Self>
133 class EventImplementationHelper<void,Self>
136 void callback(ClockService::clock_type time);
140 detail::EventBinding<void> & binding();
145 /** \brief Event implementation base class
147 EventImplementation provides the base-class for all Event implementations.
149 class SomeEvent : public EventImplementation<SomeEventArg>
155 virtual void v_enable() {
156 // register cb() to be called when the event occurs
159 virtual void v_disable() {
164 // Build event argument
165 SomeEventArg arg (...);
166 // Call the event callback
172 Every event needs to implement v_enable() and v_disable(). v_enable() should register some
173 member (in the example \c cb() ) to be called whenever the event occurs, while v_disable()
174 should unregister it.
176 The \a EventType argument to EventImplementation defines the type of argument passed to the
177 user callback. It defaults to \c void. . This user callback is called from within the
178 registered member (e.g. \c cb() ) by calling the inherited callback() member. This member
179 takes an \a EventType reference as argument which will be forwarded to the user callback. If
180 available, you should also provide the \e expected event time as a second argument.
182 template <class EventType>
183 class EventImplementation
184 : public EventDescriptor,
185 public EventImplementationHelper< EventType, EventImplementation<EventType> >
188 typedef EventType Event;
189 typedef typename detail::EventArgType<EventType>::type EventArg;
191 module::Module & module() const; ///< Module in which the event is registered
192 EventManager & manager() const; ///< EventManager of the event
195 EventImplementation();
198 virtual bool v_isRegistered();
199 void setBinding(detail::EventBinding<Event> & binding);
201 detail::EventBinding<Event> * binding_;
203 friend class EventManager;
204 friend class EventImplementationHelper< EventType, EventImplementation<EventType> >;
209 //-/////////////////////////////////////////////////////////////////////////////////////////////////
210 #include "Events.cci"
211 //#include "Events.ct"
212 #include "Events.cti"
219 // c-file-style: "senf"
220 // indent-tabs-mode: nil
221 // ispell-local-dictionary: "american"
222 // compile-command: "scons -u test"
223 // comment-column: 40