senf/Scheduler/EventHook.hh

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