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