Bug 792920 - Update nsITimer.idl comments re: off main-thread use. r=mcmanus DONTBUILD
authorJason Duell <jduell.mcbugs@gmail.com>
Thu, 04 Apr 2013 11:36:07 -0700
changeset 127717 d4499dadb6e779534d556c758952e587b9c7aa67
parent 127716 795e9ec338a77719d61475ac57c7a9ec22e4156a
child 127718 ba7609e950386e7260b86b93792163f4ef73fae3
push id24512
push userryanvm@gmail.com
push dateFri, 05 Apr 2013 20:13:49 +0000
treeherdermozilla-central@139b6ba547fa [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersmcmanus
bugs792920
milestone23.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 792920 - Update nsITimer.idl comments re: off main-thread use. r=mcmanus DONTBUILD
xpcom/threads/nsITimer.idl
--- a/xpcom/threads/nsITimer.idl
+++ b/xpcom/threads/nsITimer.idl
@@ -48,21 +48,18 @@ interface nsITimerCallback : nsISupports
 %}
 
 /**
  * nsITimer instances must be initialized by calling one of the "init" methods
  * documented below.  You may also re-initialize (using one of the init()
  * methods) an existing instance to avoid the overhead of destroying and
  * creating a timer.  It is not necessary to cancel the timer in that case.
  *
- * It is not currently safe to initialize timers on any thread other than the
- * main thread (it will cause races on the timers' delay adjustment mechanism,
- * which may mess up timings).   You can, however, cancel() and/or release a
- * timer on a non-main thread (provided that its callback object has a
- * thread-safe release() function).
+ * By default a timer will fire on the thread that created it.  Set the .target
+ * attribute to fire on a different thread.
  */
 [scriptable, uuid(193fc37a-8aa4-4d29-aa57-1acd87c26b66)]
 interface nsITimer : nsISupports
 {
   /* Timer types */
 
   /**
    * Type of a timer that fires once only.
@@ -159,16 +156,19 @@ interface nsITimer : nsISupports
                         in unsigned long aDelay, 
                         in unsigned long aType);
 
   /**
    * Cancel the timer.  This method works on all types, not just on repeating
    * timers -- you might want to cancel a TYPE_ONE_SHOT timer, and even reuse
    * it by re-initializing it (to avoid object destruction and creation costs
    * by conserving one timer instance).
+   * 
+   * You can cancel() a timer on a thread other than its target, as long as 
+   * its callback object has a thread-safe release() function.
    */
   void cancel();
   
   /**
    * The millisecond delay of the timeout.
    *
    * NOTE: Re-setting the delay on a one-shot timer that has already fired
    * doesn't restart the timer. Call one of the init() methods to restart
@@ -189,16 +189,18 @@ interface nsITimer : nsISupports
   /**
    * The nsITimerCallback object passed to initWithCallback.
    */
   readonly attribute nsITimerCallback callback;
 
   /**
    * The nsIEventTarget where the callback will be dispatched. Note that this
    * target may only be set before the call to one of the init methods above.
+   * 
+   * By default the target is the thread that created the timer.
    */
   attribute nsIEventTarget target;
 };
 
 %{C++
 #define NS_TIMER_CONTRACTID "@mozilla.org/timer;1"
 #define NS_TIMER_CALLBACK_TOPIC "timer-callback"
 %}