Scheduler/EventEvent.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2008
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 /** \file
  24     \brief EventEvent public header */
  25
  26 #ifndef HH_EventEvent_
  27 #define HH_EventEvent_ 1
  28
  29 // Custom includes
  30 #include <boost/function.hpp>
  31 #include "../boost/intrusive/ilist_hook.hpp"
  32 #include "FIFORunner.hh"
  33
  34 //#include "EventEvent.mpp"
  35 ///////////////////////////////hh.p////////////////////////////////////////
  36
  37 namespace senf {
  38 namespace scheduler {
  39
  40     namespace detail {
  41         struct EventEventListTag;
  42         typedef boost::intrusive::ilist_base_hook<EventEventListTag> EventEventListBase;
  43         class EventEventDispatcher;
  44     }
  45
  46     /** \brief Event hook event
  47
  48         This event is special: It is not a real event, it is a kind of hook which is called,
  49         whenever any other event is signaled. Combining this with explicit priority specification,
  50         this can be used to implement hooks which are called before or after any other callback.
  51
  52         \code
  53         void beforeEventHook();
  54         void afterEventHook();
  55
  56         senf::scheduler::EventEvent beforeEventHookEvent (
  57             "beforeEventHook", beforeEventHook, true, senf::scheduler::EventEvent::PRIORITY_LOW);
  58         senf::scheduler::EventEvent afterEventHookEvent (
  59             "afterEventHook", afterEventHook, true, senf::scheduler::EventEvent::PRIORITY_HIGH);
  60         \endcode
  61
  62         This usage assumes, that all ordinary events are registered with \c PRIORITY_NORMAL.
  63
  64         The EventEvent class is an implementation of the RAII idiom: The event will be automatically
  65         unregistered in the EventEvent destructor. The EventEvent instance should be created within
  66         the same scope or on a scope below where the callback is defined (e.g. if the callback is a
  67         member function it should be defined as a class member).
  68       */
  69     class EventEvent
  70         : public detail::FIFORunner::TaskInfo,
  71           public detail::EventEventListBase
  72     {
  73     public:
  74         ///////////////////////////////////////////////////////////////////////////
  75         // Types
  76
  77         typedef boost::function<void ()> Callback;
  78
  79         ///////////////////////////////////////////////////////////////////////////
  80         ///\name Structors and default members
  81         ///@{
  82
  83         EventEvent(std::string const & name, Callback const & cb,
  84                    bool initiallyEnabled = true, Priority priority = PRIORITY_NORMAL);
  85                                         ///< Register an event hook
  86                                         /**< Registers \a cb to be called whenever any other event
  87                                              is signaled by the scheduler. If \a initiallyEnabled is
  88                                              set \c false, the callback will not be enabled
  89                                              automatically. Use enable() to do so.
  90                                              \param[in] name Descriptive event name (purely
  91                                                  informational)
  92                                              \param[in] cb Callback to call
  93                                              \param[in] initiallyEnabled if set \c false, do not
  94                                                  enable callback automatically.
  95                                              \param[in] priority event priority, defaults to
  96                                                  PRIORITY_NORMAL */
  97         ~EventEvent();
  98
  99         ///@}
 100         ///////////////////////////////////////////////////////////////////////////
 101
 102         void disable();                 ///< Disable event
 103         void enable();                  ///< Enable event
 104
 105         void action(Callback const & cb); ///< Change event callback
 106
 107     protected:
 108
 109     private:
 110         virtual void v_run();
 111         virtual char const * v_type() const;
 112         virtual std::string v_info() const;
 113
 114         Callback cb_;
 115
 116         friend class detail::EventEventDispatcher;
 117     };
 118
 119 }}
 120
 121 ///////////////////////////////hh.e////////////////////////////////////////
 122 #include "EventEvent.cci"
 123 //#include "EventEvent.ct"
 124 //#include "EventEvent.cti"
 125 #endif
 126
 127 \f
 128 // Local Variables:
 129 // mode: c++
 130 // fill-column: 100
 131 // comment-column: 40
 132 // c-file-style: "senf"
 133 // indent-tabs-mode: nil
 134 // ispell-local-dictionary: "american"
 135 // compile-command: "scons -u test"
 136 // End: