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 /// Instances of this class will be stored in the movie_root singleton.
  41 ///
  42 /// A timer has a function to call, a context in which to call it, a
  43 /// list of arguments and an interval specifying how often the function must be
  44 /// called.
  45 ///
  46 /// It is *not* a "smart" timer, which is
  47 /// it will *not* automatically execute at given intervals. Rather, it
  48 /// will be movie_root responsibility to execute the timer-associated
  49 /// function at regular intervals. As a facility, the Timer class provides
  50 /// an execution operator, proxying the execution to the associated function
  51 /// with properly set-up context.
  52 class DSOEXPORT Timer
  53 {
  54 public:
  55
  56     ~Timer();
  57
  58     /// Construct a Timer, enabling it.
  59     //
  60     /// @param method
  61     ///    The function to call from execution operator.
  62     ///    Will be stored in an intrusive_ptr.
  63     ///
  64     /// @param ms
  65     ///    The number of milliseconds between expires.
  66     ///
  67     /// @param this_ptr
  68     ///    The object to be used as 'this' pointer when calling the
  69     ///    associated function. Will be stored in an intrusive_ptr.
  70     ///    It is allowed to be NULL as long as fn_call is allowed
  71     ///    a NULL as 'this_ptr' (we might want to change this).
  72     ///
  73     /// @param args
  74     ///     The list of arguments to pass to the function being invoked.
  75     ///
  76     /// @param runOnce
  77     ///     If true the interval will run only once. False if omitted.
  78     Timer(as_function& method, unsigned long ms, as_object* this_ptr,
  79             const fn_call::Args& args, bool runOnce = false);
  80
  81     /// Construct the Timer to call a late-evaluated object method, enabling it.
  82     //
  83     /// @param this_ptr
  84     ///    The object to be used as 'this' pointer when calling the
  85     ///    associated function. Will be stored in an intrusive_ptr.
  86     ///    It is allowed to be NULL as long as fn_call is allowed
  87     ///    a NULL as 'this_ptr' (we might want to change this).
  88     ///
  89     /// @param methodName
  90     ///    The method name to call from execution operator.
  91     ///
  92     /// @param ms
  93     ///    The number of milliseconds between expires.
  94     ///
  95     /// @param args
  96     ///     The list of arguments to pass to the function being invoked.
  97     ///
  98     /// @param runOnce
  99     ///     If true the interval will run only once. False if omitted.
 100     Timer(as_object* obj, string_table::key methodName, unsigned long ms,
 101             const fn_call::Args& args, bool runOnce = false);
 102
 103     /// Clear the timer, ready for reuse
 104     //
 105     /// When a Timer is cleared, the expired() function
 106     /// will always return false.
 107     ///
 108     /// Use setInterval() to reset it.
 109     ///
 110     void clearInterval();
 111
 112     /// Get expiration state
 113     // /// @param now
 114     ///    Current time, in milliseconds.
 115     ///
 116     /// @param elapsed
 117     ///    Output parameter, will be set to the amount of milliseconds
 118     ///    elapsed since actual expiration, if expired.
 119     ///
 120     /// @return true if the timer expired, false otherwise.
 121     ///
 122     bool expired(unsigned long now, unsigned long& elapsed);
 123
 124     /// Return true if interval has been cleared.
 125     //
 126     /// Note that the timer is constructed as cleared and you
 127     /// need to call setInterval() to make it not-cleared.
 128     bool cleared() const {
 129           return _start == std::numeric_limits<unsigned long>::max();
 130     }
 131
 132     /// Execute associated function and reset state
 133     //
 134     /// After execution either the timer is cleared
 135     /// (if runOnce) or start time is incremented
 136     /// by the interval.
 137     ///
 138     /// NOTE: if the timer is cleared this call
 139     ///       results in a no-op.
 140     ///
 141     void executeAndReset();
 142
 143 #ifdef GNASH_USE_GC
 144     /// Mark all reachable resources (for GC)
 145     //
 146     /// Resources reachable from Timer are:
 147     ///
 148     ///    - Arguments list (_args)
 149     ///    - Associated function (_function)
 150     ///    - Target object (_object)
 151     ///
 152     void markReachableResources() const;
 153 #endif // GNASH_USE_GC
 154
 155 private:
 156
 157     /// Execute associated function properly setting up context
 158     void execute();
 159
 160     /// Execute associated function properly setting up context
 161     void operator() () { execute(); }
 162
 163     /// Return number of milliseconds between expirations
 164     unsigned long getInterval() const { return _interval; }
 165
 166     /// Return number of milliseconds after VM start this timer was last reset
 167     unsigned long getStart() const { return _start; }
 168
 169     /// Set timer start
 170     //
 171     /// Called by every function setting the interval.
 172     ///
 173     void start();
 174
 175     /// Number of milliseconds between expirations
 176     unsigned int _interval;
 177
 178     /// Number of milliseconds since epoch at Timer start
 179     //
 180     /// This will be numeric_limits<unsigned long>::max()
 181     /// if the timer is not active (or cleared)
 182     ///
 183     unsigned long _start;
 184
 185     /// The associated function (if statically-bound) stored in
 186     /// an intrusive pointer
 187     as_function* _function;
 188
 189     string_table::key _methodName;
 190
 191     /// Context for the function call. Will be used as 'this' pointer.
 192     as_object* _object;
 193
 194     /// List of arguments
 195     //
 196     /// This must be copied before passing to a function call.
 197     const fn_call::Args _args;
 198
 199     /// True if the timer should execute only once (for setTimeout)
 200     bool _runOnce;
 201 };
 202
 203 } // namespace gnash
 204
 205 #endif