xpcom/threads/nsITimer.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7 #include  "nsINamed.idl"
   8
   9 interface nsIObserver;
  10 interface nsIEventTarget;
  11
  12 %{C++
  13 #include "mozilla/MemoryReporting.h"
  14 #include "mozilla/TimeStamp.h"
  15 #include <functional>
  16
  17 /**
  18  * The signature of the timer callback function passed to initWithFuncCallback.
  19  * This is the function that will get called when the timer expires if the
  20  * timer is initialized via initWithFuncCallback.
  21  *
  22  * @param aTimer the timer which has expired
  23  * @param aClosure opaque parameter passed to initWithFuncCallback
  24  */
  25 class nsITimer;
  26 typedef void (*nsTimerCallbackFunc) (nsITimer *aTimer, void *aClosure);
  27 %}
  28
  29 native nsTimerCallbackFunc(nsTimerCallbackFunc);
  30 [ref] native TimeDuration(mozilla::TimeDuration);
  31
  32 /**
  33  * The callback interface for timers.
  34  */
  35 interface nsITimer;
  36
  37 [function, scriptable, uuid(a796816d-7d47-4348-9ab8-c7aeb3216a7d)]
  38 interface nsITimerCallback : nsISupports
  39 {
  40   /**
  41    * @param aTimer the timer which has expired
  42    */
  43   void notify(in nsITimer timer);
  44 };
  45
  46 %{C++
  47 // Two timer deadlines must differ by less than half the PRIntervalTime domain.
  48 #define DELAY_INTERVAL_LIMIT    PR_BIT(8 * sizeof(PRIntervalTime) - 1)
  49 %}
  50
  51 /**
  52  * nsITimer instances must be initialized by calling one of the "init" methods
  53  * documented below.  You may also re-initialize (using one of the init()
  54  * methods) an existing instance to avoid the overhead of destroying and
  55  * creating a timer.  It is not necessary to cancel the timer in that case.
  56  *
  57  * By default a timer will fire on the thread that created it.  Set the .target
  58  * attribute to fire on a different thread.  Once you have set a timer's .target
  59  * and called one of its init functions, any further interactions with the timer
  60  * (calling cancel(), changing member fields, etc) should only be done by the
  61  * target thread, or races may occur with bad results like timers firing after
  62  * they've been canceled, and/or not firing after re-initiatization.
  63  */
  64 [scriptable, builtinclass, uuid(3de4b105-363c-482c-a409-baac83a01bfc)]
  65 interface nsITimer : nsISupports
  66 {
  67   /* Timer types */
  68
  69   /**
  70    * Type of a timer that fires once only.
  71    */
  72   const short TYPE_ONE_SHOT = 0;
  73
  74   /**
  75    * After firing, a TYPE_REPEATING_SLACK timer is stopped and not restarted
  76    * until its callback completes.  Specified timer period will be at least
  77    * the time between when processing for last firing the callback completes
  78    * and when the next firing occurs.
  79    *
  80    * This is the preferable repeating type for most situations.
  81    */
  82   const short TYPE_REPEATING_SLACK = 1;
  83
  84   /**
  85    * TYPE_REPEATING_PRECISE is just a synonym for
  86    * TYPE_REPEATING_PRECISE_CAN_SKIP. They used to be distinct, but the old
  87    * TYPE_REPEATING_PRECISE kind was similar to TYPE_REPEATING_PRECISE_CAN_SKIP
  88    * while also being less useful. So the distinction was removed.
  89    */
  90   const short TYPE_REPEATING_PRECISE = 2;
  91
  92   /**
  93    * A TYPE_REPEATING_PRECISE_CAN_SKIP repeating timer aims to have constant
  94    * period between firings.  The processing time for each timer callback will
  95    * not influence the timer period.  If the callback finishes after the next
  96    * firing(s) should have happened (either because the callback took a long
  97    * time, or the callback was called extremely late), that firing(s) is
  98    * skipped, but the following sequence of firing times will not be altered.
  99    * This timer type guarantees that it will not queue up new events to fire
 100    * the callback until the previous callback event finishes firing.  This is
 101    * the only non-slack timer available.
 102    */
 103   const short TYPE_REPEATING_PRECISE_CAN_SKIP = 3;
 104
 105   /**
 106    * Same as TYPE_REPEATING_SLACK with the exception that idle events
 107    * won't yield to timers with this type.  Use this when you want an
 108    * idle callback to be scheduled to run even though this timer is
 109    * about to fire.
 110    */
 111   const short TYPE_REPEATING_SLACK_LOW_PRIORITY = 4;
 112
 113   /**
 114    * Same as TYPE_ONE_SHOT with the exception that idle events won't
 115    * yield to timers with this type.  Use this when you want an idle
 116    * callback to be scheduled to run even though this timer is about
 117    * to fire.
 118    */
 119   const short TYPE_ONE_SHOT_LOW_PRIORITY = 5;
 120
 121   /**
 122    * Initialize a timer that will fire after the said delay.
 123    * A user must keep a reference to this timer till it is
 124    * is no longer needed or has been cancelled.
 125    *
 126    * @param aObserver   the callback object that observes the
 127    *                    ``timer-callback'' topic with the subject being
 128    *                    the timer itself when the timer fires:
 129    *
 130    *                    observe(nsISupports aSubject, => nsITimer
 131    *                            string aTopic,        => ``timer-callback''
 132    *                            wstring data          =>  null
 133    *
 134    * @param aDelayInMs  delay in milliseconds for timer to fire
 135    * @param aType       timer type per TYPE* consts defined above
 136    */
 137   void init(in nsIObserver aObserver, in unsigned long aDelayInMs,
 138             in unsigned long aType);
 139
 140
 141   /**
 142    * Initialize a timer to fire after the given millisecond interval.
 143    * This version takes a callback object.
 144    *
 145    * @param aFunc       nsITimerCallback interface to call when timer expires
 146    * @param aDelayInMs  The millisecond interval
 147    * @param aType       Timer type per TYPE* consts defined above
 148    */
 149   void initWithCallback(in nsITimerCallback aCallback,
 150                         in unsigned long aDelayInMs,
 151                         in unsigned long aType);
 152
 153   /**
 154    * Initialize a timer to fire after the high resolution TimeDuration.
 155    * This version takes a callback object.
 156    *
 157    * @param aFunc      nsITimerCallback interface to call when timer expires
 158    * @param aDelay     The high resolution interval
 159    * @param aType      Timer type per TYPE* consts defined above
 160    */
 161   [noscript] void initHighResolutionWithCallback(in nsITimerCallback aCallback,
 162                                                  [const] in TimeDuration aDelay,
 163                                                  in unsigned long aType);
 164
 165   /**
 166    * Cancel the timer.  This method works on all types, not just on repeating
 167    * timers -- you might want to cancel a TYPE_ONE_SHOT timer, and even reuse
 168    * it by re-initializing it (to avoid object destruction and creation costs
 169    * by conserving one timer instance).
 170    */
 171   void cancel();
 172
 173   /**
 174    * Like initWithFuncCallback, but also takes a name for the timer; the name
 175    * will be used when timer profiling is enabled via the "TimerFirings" log
 176    * module.
 177    *
 178    * @param aFunc      The function to invoke
 179    * @param aClosure   An opaque pointer to pass to that function
 180    * @param aDelay     The millisecond interval
 181    * @param aType      Timer type per TYPE* consts defined above
 182    * @param aName      The timer's name
 183    */
 184   [noscript] void initWithNamedFuncCallback(in nsTimerCallbackFunc aCallback,
 185                                             in voidPtr aClosure,
 186                                             in unsigned long aDelay,
 187                                             in unsigned long aType,
 188                                             in string aName);
 189
 190   /**
 191    * Initialize a timer to fire after the high resolution TimeDuration.
 192    * This version takes a named function callback.
 193    *
 194    * @param aFunc      The function to invoke
 195    * @param aClosure   An opaque pointer to pass to that function
 196    * @param aDelay     The high resolution interval
 197    * @param aType      Timer type per TYPE* consts defined above
 198    * @param aName      The timer's name
 199    */
 200   [noscript] void initHighResolutionWithNamedFuncCallback(
 201                       in nsTimerCallbackFunc aCallback,
 202                       in voidPtr aClosure,
 203                       [const] in TimeDuration aDelay,
 204                       in unsigned long aType,
 205                       in string aName);
 206
 207   /**
 208    * The millisecond delay of the timeout.
 209    *
 210    * NOTE: Re-setting the delay on a one-shot timer that has already fired
 211    * doesn't restart the timer. Call one of the init() methods to restart
 212    * a one-shot timer.
 213    */
 214   attribute unsigned long delay;
 215
 216   /**
 217    * The timer type - one of the above TYPE_* constants.
 218    */
 219   attribute unsigned long type;
 220
 221   /**
 222    * The opaque pointer pass to initWithFuncCallback.
 223    */
 224   [noscript] readonly attribute voidPtr closure;
 225
 226   /**
 227    * The nsITimerCallback object passed to initWithCallback.
 228    */
 229   readonly attribute nsITimerCallback callback;
 230
 231   /**
 232    * The nsIEventTarget where the callback will be dispatched. Note that this
 233    * target may only be set before the call to one of the init methods above.
 234    *
 235    * By default the target is the thread that created the timer.
 236    */
 237   attribute nsIEventTarget target;
 238
 239   /**
 240    * The number of microseconds this nsITimer implementation can possibly
 241    * fire early.
 242    */
 243   [noscript] readonly attribute unsigned long allowedEarlyFiringMicroseconds;
 244
 245 %{C++
 246   virtual size_t SizeOfIncludingThis(mozilla::MallocSizeOf aMallocSizeOf) const = 0;
 247 %}
 248 };
 249
 250 %{C++
 251 #include "nsCOMPtr.h"
 252
 253 already_AddRefed<nsITimer> NS_NewTimer();
 254
 255 already_AddRefed<nsITimer> NS_NewTimer(nsIEventTarget* aTarget);
 256
 257 nsresult
 258 NS_NewTimerWithObserver(nsITimer** aTimer,
 259                         nsIObserver* aObserver,
 260                         uint32_t aDelay,
 261                         uint32_t aType,
 262                         nsIEventTarget* aTarget = nullptr);
 263 mozilla::Result<nsCOMPtr<nsITimer>, nsresult>
 264 NS_NewTimerWithObserver(nsIObserver* aObserver,
 265                         uint32_t aDelay,
 266                         uint32_t aType,
 267                         nsIEventTarget* aTarget = nullptr);
 268
 269 nsresult
 270 NS_NewTimerWithCallback(nsITimer** aTimer,
 271                         nsITimerCallback* aCallback,
 272                         uint32_t aDelay,
 273                         uint32_t aType,
 274                         nsIEventTarget* aTarget = nullptr);
 275 mozilla::Result<nsCOMPtr<nsITimer>, nsresult>
 276 NS_NewTimerWithCallback(nsITimerCallback* aCallback,
 277                         uint32_t aDelay,
 278                         uint32_t aType,
 279                         nsIEventTarget* aTarget = nullptr);
 280
 281 nsresult
 282 NS_NewTimerWithCallback(nsITimer** aTimer,
 283                         nsITimerCallback* aCallback,
 284                         const mozilla::TimeDuration& aDelay,
 285                         uint32_t aType,
 286                         nsIEventTarget* aTarget = nullptr);
 287 mozilla::Result<nsCOMPtr<nsITimer>, nsresult>
 288 NS_NewTimerWithCallback(nsITimerCallback* aCallback,
 289                         const mozilla::TimeDuration& aDelay,
 290                         uint32_t aType,
 291                         nsIEventTarget* aTarget = nullptr);
 292
 293 nsresult
 294 NS_NewTimerWithCallback(nsITimer** aTimer,
 295                         std::function<void(nsITimer*)>&& aCallback,
 296                         uint32_t aDelay,
 297                         uint32_t aType,
 298                         const char* aNameString,
 299                         nsIEventTarget* aTarget = nullptr);
 300 mozilla::Result<nsCOMPtr<nsITimer>, nsresult>
 301 NS_NewTimerWithCallback(std::function<void(nsITimer*)>&& aCallback,
 302                         uint32_t aDelay,
 303                         uint32_t aType,
 304                         const char* aNameString,
 305                         nsIEventTarget* aTarget = nullptr);
 306
 307 nsresult
 308 NS_NewTimerWithCallback(nsITimer** aTimer,
 309                         std::function<void(nsITimer*)>&& aCallback,
 310                         const mozilla::TimeDuration& aDelay,
 311                         uint32_t aType,
 312                         const char* aNameString,
 313                         nsIEventTarget* aTarget = nullptr);
 314 mozilla::Result<nsCOMPtr<nsITimer>, nsresult>
 315 NS_NewTimerWithCallback(std::function<void(nsITimer*)>&& aCallback,
 316                         const mozilla::TimeDuration& aDelay,
 317                         uint32_t aType,
 318                         const char* aNameString,
 319                         nsIEventTarget* aTarget = nullptr);
 320
 321 nsresult
 322 NS_NewTimerWithFuncCallback(nsITimer** aTimer,
 323                             nsTimerCallbackFunc aCallback,
 324                             void* aClosure,
 325                             uint32_t aDelay,
 326                             uint32_t aType,
 327                             const char* aNameString,
 328                             nsIEventTarget* aTarget = nullptr);
 329 mozilla::Result<nsCOMPtr<nsITimer>, nsresult>
 330 NS_NewTimerWithFuncCallback(nsTimerCallbackFunc aCallback,
 331                             void* aClosure,
 332                             uint32_t aDelay,
 333                             uint32_t aType,
 334                             const char* aNameString,
 335                             nsIEventTarget* aTarget = nullptr);
 336
 337 nsresult
 338 NS_NewTimerWithFuncCallback(nsITimer** aTimer,
 339                             nsTimerCallbackFunc aCallback,
 340                             void* aClosure,
 341                             const mozilla::TimeDuration& aDelay,
 342                             uint32_t aType,
 343                             const char* aNameString,
 344                             nsIEventTarget* aTarget = nullptr);
 345 mozilla::Result<nsCOMPtr<nsITimer>, nsresult>
 346 NS_NewTimerWithFuncCallback(nsTimerCallbackFunc aCallback,
 347                             void* aClosure,
 348                             const mozilla::TimeDuration& aDelay,
 349                             uint32_t aType,
 350                             const char* aNameString,
 351                             nsIEventTarget* aTarget = nullptr);
 352
 353 #define NS_TIMER_CONTRACTID "@mozilla.org/timer;1"
 354 #define NS_TIMER_CALLBACK_TOPIC "timer-callback"
 355
 356 #ifndef RELEASE_OR_BETA
 357 #undef NS_DECL_NSITIMERCALLBACK
 358 #define NS_DECL_NSITIMERCALLBACK                                        \
 359   NS_IMETHOD Notify(nsITimer *timer) override;                          \
 360   inline void _ensure_GetName_exists(void) {                            \
 361     static_assert(std::is_convertible<decltype(this), nsINamed*>::value, \
 362                   "nsITimerCallback implementations must also implement nsINamed");     \
 363   }
 364 #endif
 365 %}