1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/xpcom/threads/nsITimer.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,203 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + * This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIObserver;
1.12 +interface nsIEventTarget;
1.13 +
1.14 +%{C++
1.15 +/**
1.16 + * The signature of the timer callback function passed to initWithFuncCallback.
1.17 + * This is the function that will get called when the timer expires if the
1.18 + * timer is initialized via initWithFuncCallback.
1.19 + *
1.20 + * @param aTimer the timer which has expired
1.21 + * @param aClosure opaque parameter passed to initWithFuncCallback
1.22 + */
1.23 +class nsITimer;
1.24 +typedef void (*nsTimerCallbackFunc) (nsITimer *aTimer, void *aClosure);
1.25 +%}
1.26 +
1.27 +native nsTimerCallbackFunc(nsTimerCallbackFunc);
1.28 +
1.29 +/**
1.30 + * The callback interface for timers.
1.31 + */
1.32 +interface nsITimer;
1.33 +
1.34 +[function, scriptable, uuid(a796816d-7d47-4348-9ab8-c7aeb3216a7d)]
1.35 +interface nsITimerCallback : nsISupports
1.36 +{
1.37 + /**
1.38 + * @param aTimer the timer which has expired
1.39 + */
1.40 + void notify(in nsITimer timer);
1.41 +};
1.42 +
1.43 +%{C++
1.44 +// Two timer deadlines must differ by less than half the PRIntervalTime domain.
1.45 +#define DELAY_INTERVAL_LIMIT PR_BIT(8 * sizeof(PRIntervalTime) - 1)
1.46 +%}
1.47 +
1.48 +/**
1.49 + * nsITimer instances must be initialized by calling one of the "init" methods
1.50 + * documented below. You may also re-initialize (using one of the init()
1.51 + * methods) an existing instance to avoid the overhead of destroying and
1.52 + * creating a timer. It is not necessary to cancel the timer in that case.
1.53 + *
1.54 + * By default a timer will fire on the thread that created it. Set the .target
1.55 + * attribute to fire on a different thread. Once you have set a timer's .target
1.56 + * and called one of its init functions, any further interactions with the timer
1.57 + * (calling cancel(), changing member fields, etc) should only be done by the
1.58 + * target thread, or races may occur with bad results like timers firing after
1.59 + * they've been canceled, and/or not firing after re-initiatization.
1.60 + */
1.61 +[scriptable, uuid(193fc37a-8aa4-4d29-aa57-1acd87c26b66)]
1.62 +interface nsITimer : nsISupports
1.63 +{
1.64 + /* Timer types */
1.65 +
1.66 + /**
1.67 + * Type of a timer that fires once only.
1.68 + */
1.69 + const short TYPE_ONE_SHOT = 0;
1.70 +
1.71 + /**
1.72 + * After firing, a TYPE_REPEATING_SLACK timer is stopped and not restarted
1.73 + * until its callback completes. Specified timer period will be at least
1.74 + * the time between when processing for last firing the callback completes
1.75 + * and when the next firing occurs.
1.76 + *
1.77 + * This is the preferable repeating type for most situations.
1.78 + */
1.79 + const short TYPE_REPEATING_SLACK = 1;
1.80 +
1.81 + /**
1.82 + * An TYPE_REPEATING_PRECISE repeating timer aims to have constant period
1.83 + * between firings. The processing time for each timer callback should not
1.84 + * influence the timer period. However, if the processing for the last
1.85 + * timer firing could not be completed until just before the next firing
1.86 + * occurs, then you could have two timer notification routines being
1.87 + * executed in quick succession. Furthermore, if your callback processing
1.88 + * time is longer than the timer period, then the timer will post more
1.89 + * notifications while your callback is running. For example, if a
1.90 + * REPEATING_PRECISE timer has a 10ms period and a callback takes 50ms,
1.91 + * then by the time the callback is done there will be 5 events to run the
1.92 + * timer callback in the event queue. Furthermore, the next scheduled time
1.93 + * will always advance by exactly the delay every time the timer fires.
1.94 + * This means that if the clock increments without the timer thread running
1.95 + * (e.g. the computer is asleep) when the timer thread gets to run again it
1.96 + * will post all the events that it "missed" while it wasn't running. Use
1.97 + * this timer type with extreme caution. Chances are, this is not what you
1.98 + * want.
1.99 + */
1.100 + const short TYPE_REPEATING_PRECISE = 2;
1.101 +
1.102 + /**
1.103 + * A TYPE_REPEATING_PRECISE_CAN_SKIP repeating timer aims to have constant
1.104 + * period between firings. The processing time for each timer callback
1.105 + * should not influence the timer period. However this timer type
1.106 + * guarantees that it will not queue up new events to fire the callback
1.107 + * until the previous callback event finishes firing. If the callback
1.108 + * takes a long time, then the next callback will be scheduled immediately
1.109 + * afterward, but only once, unlike TYPE_REPEATING_PRECISE. If you want a
1.110 + * non-slack timer, you probably want this one.
1.111 + */
1.112 + const short TYPE_REPEATING_PRECISE_CAN_SKIP = 3;
1.113 +
1.114 + /**
1.115 + * Initialize a timer that will fire after the said delay.
1.116 + * A user must keep a reference to this timer till it is
1.117 + * is no longer needed or has been cancelled.
1.118 + *
1.119 + * @param aObserver the callback object that observes the
1.120 + * ``timer-callback'' topic with the subject being
1.121 + * the timer itself when the timer fires:
1.122 + *
1.123 + * observe(nsISupports aSubject, => nsITimer
1.124 + * string aTopic, => ``timer-callback''
1.125 + * wstring data => null
1.126 + *
1.127 + * @param aDelay delay in milliseconds for timer to fire
1.128 + * @param aType timer type per TYPE* consts defined above
1.129 + */
1.130 + void init(in nsIObserver aObserver, in unsigned long aDelay,
1.131 + in unsigned long aType);
1.132 +
1.133 +
1.134 + /**
1.135 + * Initialize a timer to fire after the given millisecond interval.
1.136 + * This version takes a function to call and a closure to pass to
1.137 + * that function.
1.138 + *
1.139 + * @param aFunc The function to invoke
1.140 + * @param aClosure An opaque pointer to pass to that function
1.141 + * @param aDelay The millisecond interval
1.142 + * @param aType Timer type per TYPE* consts defined above
1.143 + */
1.144 + [noscript] void initWithFuncCallback(in nsTimerCallbackFunc aCallback,
1.145 + in voidPtr aClosure,
1.146 + in unsigned long aDelay,
1.147 + in unsigned long aType);
1.148 +
1.149 + /**
1.150 + * Initialize a timer to fire after the given millisecond interval.
1.151 + * This version takes a function to call.
1.152 + *
1.153 + * @param aFunc nsITimerCallback interface to call when timer expires
1.154 + * @param aDelay The millisecond interval
1.155 + * @param aType Timer type per TYPE* consts defined above
1.156 + */
1.157 + void initWithCallback(in nsITimerCallback aCallback,
1.158 + in unsigned long aDelay,
1.159 + in unsigned long aType);
1.160 +
1.161 + /**
1.162 + * Cancel the timer. This method works on all types, not just on repeating
1.163 + * timers -- you might want to cancel a TYPE_ONE_SHOT timer, and even reuse
1.164 + * it by re-initializing it (to avoid object destruction and creation costs
1.165 + * by conserving one timer instance).
1.166 + */
1.167 + void cancel();
1.168 +
1.169 + /**
1.170 + * The millisecond delay of the timeout.
1.171 + *
1.172 + * NOTE: Re-setting the delay on a one-shot timer that has already fired
1.173 + * doesn't restart the timer. Call one of the init() methods to restart
1.174 + * a one-shot timer.
1.175 + */
1.176 + attribute unsigned long delay;
1.177 +
1.178 + /**
1.179 + * The timer type - one of the above TYPE_* constants.
1.180 + */
1.181 + attribute unsigned long type;
1.182 +
1.183 + /**
1.184 + * The opaque pointer pass to initWithFuncCallback.
1.185 + */
1.186 + [noscript] readonly attribute voidPtr closure;
1.187 +
1.188 + /**
1.189 + * The nsITimerCallback object passed to initWithCallback.
1.190 + */
1.191 + readonly attribute nsITimerCallback callback;
1.192 +
1.193 + /**
1.194 + * The nsIEventTarget where the callback will be dispatched. Note that this
1.195 + * target may only be set before the call to one of the init methods above.
1.196 + *
1.197 + * By default the target is the thread that created the timer.
1.198 + */
1.199 + attribute nsIEventTarget target;
1.200 +};
1.201 +
1.202 +%{C++
1.203 +#define NS_TIMER_CONTRACTID "@mozilla.org/timer;1"
1.204 +#define NS_TIMER_CALLBACK_TOPIC "timer-callback"
1.205 +%}
1.206 +
