senf/Scheduler/TimerEvent.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 TimerDispatcher public header */
  25
  26 #ifndef HH_SENF_Scheduler_TimerEvent_
  27 #define HH_SENF_Scheduler_TimerEvent_ 1
  28
  29 // Custom includes
  30 #include <signal.h>
  31 #include <boost/intrusive/iset_hook.hpp>
  32 #include "ClockService.hh"
  33 #include "FdManager.hh"
  34 #include "FIFORunner.hh"
  35 #include "../Utils/Logger/SenfLog.hh"
  36
  37 //#include "TimerEvent.mpp"
  38 ///////////////////////////////hh.p////////////////////////////////////////
  39
  40 namespace senf {
  41 namespace scheduler {
  42
  43     namespace detail {
  44         struct TimerSetTag;
  45         typedef boost::intrusive::iset_base_hook<TimerSetTag> TimerSetBase;
  46         struct TimerSetCompare;
  47         class TimerDispatcher;
  48     }
  49
  50     /** \brief Deadline timer event
  51
  52         The TimerEvent class registers a deadline timer callback which will be called when the
  53         timer expires.
  54
  55         Timer events are implemented using POSIX timers. Depending on kernel features, the timer
  56         resolution will be far more precise than the linux clock tick resolution. The nominal timer
  57         resolution is 1 nanosecond.
  58
  59         The timeout time is set as \e absolute time as returned by the senf::ClockService. After
  60         expiration, the timer will be disabled. It may be re-enabled by setting a new timeout time.
  61         It is also possible to change a running timer resetting the timeout time.
  62
  63         The TimerEvent class is an implementation of the RAII idiom: The event will be automatically
  64         unregistered in the TimerEvent destructor. The TimerEvent instance should be created
  65         within the same scope or on a scope below where the callback is defined (e.g. if the
  66         callback is a member function it should be defined as a class member).
  67      */
  68     class TimerEvent
  69         : public detail::FIFORunner::TaskInfo,
  70           public detail::TimerSetBase
  71     {
  72     public:
  73         ///////////////////////////////////////////////////////////////////////////
  74         // Types
  75
  76         typedef boost::function<void ()> Callback;
  77
  78         ///////////////////////////////////////////////////////////////////////////
  79         ///\name Structors and default members
  80         ///@{
  81
  82         TimerEvent(std::string const & name, Callback const & cb, ClockService::clock_type timeout,
  83                    bool initiallyEnabled = true);
  84                                         ///< Register a timer event
  85                                         /**< Registers \a cb to be called as soon as possible after
  86                                              the time \a timeout is reached. If \a initiallyEnabled
  87                                              is set \c false, the callback will not be enabled
  88                                              automatically. Use enable() to do so.
  89                                              \param[in] name Descriptive timer name (purely
  90                                                  informational)
  91                                              \param[in] cb Callback to call
  92                                              \param[in] timeout timeout time after the timer
  93                                                  will be disabled
  94                                              \param[in] initiallyEnabled if set \c false, do not
  95                                                  enable callback automatically. */
  96         TimerEvent(std::string const & name, Callback const & cb);
  97                                         ///< Create a timer event
  98                                         /**< Creates a timer event for callback \a cb. The timer is
  99                                              initially disabled. Use the timeout() member to set the
 100                                              timeout time.
 101                                              \param[in] name Descriptive timer name (purely
 102                                                  informational)
 103                                              \param[in] cb Callback to call. */
 104         ~TimerEvent();
 105
 106         ///@}
 107         ///////////////////////////////////////////////////////////////////////////
 108
 109         void disable();                 ///< Disable timer
 110         void enable();                  ///< Enable timer
 111
 112         void action(Callback const & cb); ///< Change timer event callback
 113         void timeout(ClockService::clock_type timeout, bool initiallyEnabled=true);
 114                                         ///< Re-arm or move timeout
 115                                         /**< \param[in] timeout new timeout time
 116                                              \param[in] initiallyEnabled if set \c false, do not
 117                                                  enable callback automatically. */
 118         ClockService::clock_type timeout() const;
 119                                         ///< Get current/last timeout value
 120
 121     private:
 122         virtual void v_run();
 123         virtual char const * v_type() const;
 124         virtual std::string v_info() const;
 125
 126         Callback cb_;
 127         ClockService::clock_type timeout_;
 128
 129         friend class detail::TimerDispatcher;
 130         friend class detail::TimerSetCompare;
 131     };
 132
 133 }}
 134
 135 ///////////////////////////////hh.e////////////////////////////////////////
 136 #include "TimerEvent.cci"
 137 //#include "TimerEvent.ct"
 138 //#include "TimerEvent.cti"
 139 #endif
 140
 141 \f
 142 // Local Variables:
 143 // mode: c++
 144 // fill-column: 100
 145 // comment-column: 40
 146 // c-file-style: "senf"
 147 // indent-tabs-mode: nil
 148 // ispell-local-dictionary: "american"
 149 // compile-command: "scons -u test"
 150 // End: