developer.intra2net.com Git - libasyncio/blob - asyncio/async_callout.hpp

   1 /*
   2 The software in this package is distributed under the GNU General
   3 Public License version 2 (with a special exception described below).
   4
   5 A copy of GNU General Public License (GPL) is included in this distribution,
   6 in the file COPYING.GPL.
   7
   8 As a special exception, if other files instantiate templates or use macros
   9 or inline functions from this file, or you compile this file and link it
  10 with other works to produce a work based on this file, this file
  11 does not by itself cause the resulting work to be covered
  12 by the GNU General Public License.
  13
  14 However the source code for this file must still be made available
  15 in accordance with section (3) of the GNU General Public License.
  16
  17 This exception does not invalidate any other reasons why a work based
  18 on this file might be covered by the GNU General Public License.
  19 */
  20 /**
  21  * @file
  22  * @brief provides a method for delayed execution of functions.
  23  *
  24  * @copyright &copy; Copyright 2008-2009 by Intra2net AG
  25  */
  26 #ifndef ___ASYNC_CALLOUT_HPP__
  27 #define ___ASYNC_CALLOUT_HPP__
  28
  29 #include "async_io.hpp"
  30
  31 #include <boost/enable_shared_from_this.hpp>
  32 #include <boost/weak_ptr.hpp>
  33 #include <boost/shared_ptr.hpp>
  34
  35
  36 namespace AsyncIo
  37 {
  38
  39 // forward declarations:
  40 namespace Detail {
  41
  42 class Caller;
  43
  44 typedef boost::shared_ptr< Caller > CallerPtr;
  45 typedef boost::weak_ptr< Caller > CallerWeakPtr;
  46
  47 } // eo namespace Detail
  48
  49
  50 /**
  51  * @brief represents an id for a deferred call.
  52  *
  53  * Also provides methods for modifying the call
  54  * (like thaw or delete it).
  55  */
  56 class CallOutId
  57 {
  58       friend class Detail::Caller;
  59
  60    public:
  61       CallOutId();
  62
  63       unsigned long getValue() const {return m_value;}
  64
  65       bool thaw() const;
  66       bool remove();
  67
  68       bool active() const;
  69       bool frozen() const;
  70
  71       MilliTime remaining_time();
  72
  73    private:
  74
  75       CallOutId(unsigned long value);
  76
  77    private:
  78
  79       unsigned long m_value;
  80
  81       Detail::CallerWeakPtr m_caller_weak_ptr;
  82
  83 }; // eo class CallOutId
  84
  85
  86
  87 /*
  88 **
  89 */
  90
  91 namespace Detail {
  92
  93 /**
  94  * @brief tool class for holding and executing a deferred call.
  95  *
  96  */
  97 class Caller
  98 : public TimerBase
  99 , public boost::enable_shared_from_this< Caller >
 100 {
 101    public:
 102       Caller( boost::function< void() > f, long delta_sec, long delta_msec=0, bool frozen=false );
 103       virtual ~Caller();
 104
 105       CallOutId getCallOutId() const { return m_call_out_id; }
 106
 107       bool thaw();
 108
 109       bool joinId();
 110
 111       bool frozen() const;
 112
 113    protected:
 114
 115       virtual void execute();
 116
 117    private:
 118
 119       CallOutId m_call_out_id;
 120       boost::function< void() > m_func;
 121       bool m_waiting;
 122 }; // eo class Caller
 123
 124
 125 } // eo namespace Detail
 126
 127 /*
 128 **
 129 */
 130
 131 /**
 132  * @brief initiates a deferred call of a function.
 133  *
 134  * @param f the function which should be called.
 135  * @param delta_sec the delta time (in seconds) when the function should be called.
 136  * @return an id to identify the call (may be used for preliminary removal of the call)
 137  *
 138  * A deferred call is done by passing a function object and a delay when it should
 139  * be called.
 140  * The backend loop will call the function after the delay is passed and the backend loop is active.
 141  *
 142  * Thus the call might not not be exactly after the desired delay, but at least this time has
 143  * to pass until the function is called.
 144  *
 145  * The result id can be used to remove the call if it becomes obsolete.
 146  * This is useful when You call timeout handlers and can remove them if an event happens and
 147  * obsoletes the timeout call.
 148  *
 149  * @see CallOutId
 150  */
 151 template< typename F >
 152 CallOutId callOut( boost::function< void() > f, F delta_sec );
 153
 154 template<> CallOutId callOut( boost::function< void() > f, long delta_sec );
 155 template<> CallOutId callOut( boost::function< void() > f, double delta_sec );
 156 template<> CallOutId callOut( boost::function< void() > f, float delta_sec );
 157 template<> CallOutId callOut( boost::function< void() > f, int delta_sec );
 158
 159
 160 /**
 161  * @brief initiates a frozen call of a function.
 162  *
 163  * @param f the function which should be called.
 164  * @param delta_sec the delta time (in seconds) when the call will be (silently) removed.
 165  * @return an id to identify the call; necessary for thaw the call.
 166  *
 167  * A frozen call is a function call which will be prepared for a given period of time
 168  * but not executed. Within that time period that call might be activated ("thawed")
 169  * which means the call will be executed the next time when the backend loop is running.
 170  * If the prepared call is not activated, then it vanishes.
 171  *
 172  * The returned call id provides a method to thaw a frozen call.
 173  *
 174  * @see CallOutId
 175  */
 176 template< typename F >
 177 CallOutId frozenCall( boost::function< void() > f, F delta_sec);
 178
 179 template<> CallOutId frozenCall( boost::function< void() > f, long delta_sec );
 180 template<> CallOutId frozenCall( boost::function< void() > f, double delta_sec );
 181 template<> CallOutId frozenCall( boost::function< void() > f, float delta_sec );
 182 template<> CallOutId frozenCall( boost::function< void() > f, int delta_sec );
 183
 184
 185
 186 bool removeCallOut( CallOutId& id );
 187
 188
 189 } // eo namespace AsyncIo
 190
 191 #endif