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