libcore/Timers.h

   1 //
   2 //   Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010 Free Software
   3 //   Foundation, Inc
   4 //
   5 // This program is free software; you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation; either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // This program is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with this program; if not, write to the Free Software
  17 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  18
  19 #ifndef HAVE_TIMERS_H
  20 #define HAVE_TIMERS_H
  21
  22 #include "dsodefs.h"
  23 #include "smart_ptr.h"
  24 #include "fn_call.h"
  25
  26 #include <string>
  27 #include <limits>
  28
  29 // Forward declarations
  30 namespace gnash {
  31     class as_function;
  32     class as_object;
  33 }
  34
  35 namespace gnash {
  36
  37 /// An interval timer.
  38 //
  39 /// This is constructed when _global.setInterval() is called.
  40 ///
  41 /// A timer has a function to call, a context in which to call it, a
  42 /// list of arguments and an interval specifying how often the function must be
  43 /// called.
  44 ///
  45 /// It is *not* a "smart" timer, which is
  46 /// it will *not* automatically execute at given intervals. Rather, it
  47 /// will be movie_root responsibility to execute the timer-associated
  48 /// function at regular intervals. As a facility, the Timer class provides
  49 /// an execution operator, proxying the execution to the associated function
  50 /// with properly set-up context.
  51 class DSOEXPORT Timer
  52 {
  53 public:
  54
  55     ~Timer();
  56
  57     /// Construct a Timer, enabling it.
  58     //
  59     /// @param method
  60     ///    The function to call from execution operator.
  61     ///    Will be stored in an intrusive_ptr.
  62     ///
  63     /// @param ms
  64     ///    The number of milliseconds between expires.
  65     ///
  66     /// @param this_ptr
  67     ///    The object to be used as 'this' pointer when calling the
  68     ///    associated function. Will be stored in an intrusive_ptr.
  69     ///    It is allowed to be NULL as long as fn_call is allowed
  70     ///    a NULL as 'this_ptr' (we might want to change this).
  71     ///
  72     /// @param args
  73     ///     The list of arguments to pass to the function being invoked.
  74     ///
  75     /// @param runOnce
  76     ///     If true the interval will run only once. False if omitted.
  77     Timer(as_function& method, unsigned long ms, as_object* this_ptr,
  78             const fn_call::Args& args, bool runOnce = false);
  79
  80     /// Construct the Timer to call a late-evaluated object method, enabling it.
  81     //
  82     /// @param this_ptr
  83     ///    The object to be used as 'this' pointer when calling the
  84     ///    associated function. Will be stored in an intrusive_ptr.
  85     ///    It is allowed to be NULL as long as fn_call is allowed
  86     ///    a NULL as 'this_ptr' (we might want to change this).
  87     ///
  88     /// @param methodName
  89     ///    The method name to call from execution operator.
  90     ///
  91     /// @param ms
  92     ///    The number of milliseconds between expires.
  93     ///
  94     /// @param args
  95     ///     The list of arguments to pass to the function being invoked.
  96     ///
  97     /// @param runOnce
  98     ///     If true the interval will run only once. False if omitted.
  99     Timer(as_object* obj, const ObjectURI& methodName, unsigned long ms,
 100             const fn_call::Args& args, bool runOnce = false);
 101
 102     /// Clear the timer, ready for reuse
 103     //
 104     /// When a Timer is cleared, the expired() function
 105     /// will always return false.
 106     ///
 107     /// Use setInterval() to reset it.
 108     ///
 109     void clearInterval();
 110
 111     /// Get expiration state
 112     // /// @param now
 113     ///    Current time, in milliseconds.
 114     ///
 115     /// @param elapsed
 116     ///    Output parameter, will be set to the amount of milliseconds
 117     ///    elapsed since actual expiration, if expired.
 118     ///
 119     /// @return true if the timer expired, false otherwise.
 120     ///
 121     bool expired(unsigned long now, unsigned long& elapsed);
 122
 123     /// Return true if interval has been cleared.
 124     //
 125     /// Note that the timer is constructed as cleared and you
 126     /// need to call setInterval() to make it not-cleared.
 127     bool cleared() const {
 128           return _start == std::numeric_limits<unsigned long>::max();
 129     }
 130
 131     /// Execute associated function and reset state
 132     //
 133     /// After execution either the timer is cleared
 134     /// (if runOnce) or start time is incremented
 135     /// by the interval.
 136     ///
 137     /// NOTE: if the timer is cleared this call
 138     ///       results in a no-op.
 139     ///
 140     void executeAndReset();
 141
 142 #ifdef GNASH_USE_GC
 143     /// Mark all reachable resources (for GC)
 144     //
 145     /// Resources reachable from Timer are:
 146     ///
 147     ///    - Arguments list (_args)
 148     ///    - Associated function (_function)
 149     ///    - Target object (_object)
 150     ///
 151     void markReachableResources() const;
 152 #endif // GNASH_USE_GC
 153
 154 private:
 155
 156     /// Execute associated function properly setting up context
 157     void execute();
 158
 159     /// Execute associated function properly setting up context
 160     void operator() () { execute(); }
 161
 162     /// Return number of milliseconds between expirations
 163     unsigned long getInterval() const { return _interval; }
 164
 165     /// Return number of milliseconds after VM start this timer was last reset
 166     unsigned long getStart() const { return _start; }
 167
 168     /// Set timer start
 169     //
 170     /// Called by every function setting the interval.
 171     ///
 172     void start();
 173
 174     /// Number of milliseconds between expirations
 175     unsigned int _interval;
 176
 177     /// Number of milliseconds since epoch at Timer start
 178     //
 179     /// This will be numeric_limits<unsigned long>::max()
 180     /// if the timer is not active (or cleared)
 181     ///
 182     unsigned long _start;
 183
 184     /// The associated function (if statically-bound) stored in
 185     /// an intrusive pointer
 186     as_function* _function;
 187
 188     ObjectURI _methodName;
 189
 190     /// Context for the function call. Will be used as 'this' pointer.
 191     as_object* _object;
 192
 193     /// List of arguments
 194     //
 195     /// This must be copied before passing to a function call.
 196     const fn_call::Args _args;
 197
 198     /// True if the timer should execute only once (for setTimeout)
 199     bool _runOnce;
 200 };
 201
 202 } // namespace gnash
 203
 204 #endif