senf/Scheduler/EventHook.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 EventHook public header */
  25
  26 #ifndef HH_SENF_Scheduler_EventHook_
  27 #define HH_SENF_Scheduler_EventHook_ 1
  28
  29 // Custom includes
  30 #include <boost/function.hpp>
  31 #include <senf/boost_intrusive/ilist_hook.hpp>
  32 #include "FIFORunner.hh"
  33
  34 //#include "EventHook.mpp"
  35 ///////////////////////////////hh.p////////////////////////////////////////
  36
  37 namespace senf {
  38 namespace scheduler {
  39
  40     namespace detail {
  41         struct EventHookListTag;
  42         typedef boost::intrusive::ilist_base_hook<EventHookListTag> EventHookListBase;
  43         class EventHookDispatcher;
  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::EventHook beforeEventHookEvent (
  57             "beforeEventHook", beforeEventHook, true, senf::scheduler::EventHook::POST);
  58         senf::scheduler::EventHook afterEventHookEvent (
  59             "afterEventHook", afterEventHook, true, senf::scheduler::EventHook::PRE);
  60         \endcode
  61
  62         The EventHook class is an implementation of the RAII idiom: The event will be automatically
  63         unregistered in the EventHook destructor. The EventHook instance should be created within
  64         the same scope or on a scope below where the callback is defined (e.g. if the callback is a
  65         member function it should be defined as a class member).
  66       */
  67     class EventHook
  68         : public detail::FIFORunner::TaskInfo,
  69           public detail::EventHookListBase
  70     {
  71     public:
  72         ///////////////////////////////////////////////////////////////////////////
  73         // Types
  74
  75         typedef boost::function<void ()> Callback;
  76
  77         static Priority const PRE = PRIORITY_HIGH; ///< Execute hook BEFORE all other events
  78         static Priority const POST = PRIORITY_LOW; ///< Execute hook AFTER all other events
  79
  80         ///////////////////////////////////////////////////////////////////////////
  81         ///\name Structors and default members
  82         ///@{
  83
  84         EventHook(std::string const & name, Callback const & cb,
  85                   Priority priority, bool initiallyEnabled = true);
  86                                         ///< Register an event hook
  87                                         /**< Registers \a cb to be called whenever any other event
  88                                              is signaled by the scheduler. If \a initiallyEnabled is
  89                                              set \c false, the callback will not be enabled
  90                                              automatically. Use enable() to do so.
  91                                              \param[in] name Descriptive event name (purely
  92                                                  informational)
  93                                              \param[in] cb Callback to call
  94                                              \param[in] initiallyEnabled if set \c false, do not
  95                                                  enable callback automatically.
  96                                              \param[in] priority event priority, defaults to
  97                                                  POST */
  98         ~EventHook();
  99
 100         ///@}
 101         ///////////////////////////////////////////////////////////////////////////
 102
 103         void disable();                 ///< Disable event
 104         void enable();                  ///< Enable event
 105
 106         void action(Callback const & cb); ///< Change event callback
 107
 108     protected:
 109
 110     private:
 111         virtual void v_run();
 112         virtual char const * v_type() const;
 113         virtual std::string v_info() const;
 114
 115         Callback cb_;
 116
 117         friend class detail::EventHookDispatcher;
 118     };
 119
 120 }}
 121
 122 ///////////////////////////////hh.e////////////////////////////////////////
 123 #include "EventHook.cci"
 124 //#include "EventHook.ct"
 125 //#include "EventHook.cti"
 126 #endif
 127
 128 \f
 129 // Local Variables:
 130 // mode: c++
 131 // fill-column: 100
 132 // comment-column: 40
 133 // c-file-style: "senf"
 134 // indent-tabs-mode: nil
 135 // ispell-local-dictionary: "american"
 136 // compile-command: "scons -u test"
 137 // End: