libcore/Timers.h

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