toolkit/components/url-classifier/content/moz/alarm.js

   1 # ***** BEGIN LICENSE BLOCK *****
   2 # Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3 #
   4 # The contents of this file are subject to the Mozilla Public License Version
   5 # 1.1 (the "License"); you may not use this file except in compliance with
   6 # the License. You may obtain a copy of the License at
   7 # http://www.mozilla.org/MPL/
   8 #
   9 # Software distributed under the License is distributed on an "AS IS" basis,
  10 # WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11 # for the specific language governing rights and limitations under the
  12 # License.
  13 #
  14 # The Original Code is Google Safe Browsing.
  15 #
  16 # The Initial Developer of the Original Code is Google Inc.
  17 # Portions created by the Initial Developer are Copyright (C) 2006
  18 # the Initial Developer. All Rights Reserved.
  19 #
  20 # Contributor(s):
  21 #   Fritz Schneider <fritz@google.com> (original author)
  22 #
  23 # Alternatively, the contents of this file may be used under the terms of
  24 # either the GNU General Public License Version 2 or later (the "GPL"), or
  25 # the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  26 # in which case the provisions of the GPL or the LGPL are applicable instead
  27 # of those above. If you wish to allow use of your version of this file only
  28 # under the terms of either the GPL or the LGPL, and not to allow others to
  29 # use your version of this file under the terms of the MPL, indicate your
  30 # decision by deleting the provisions above and replace them with the notice
  31 # and other provisions required by the GPL or the LGPL. If you do not delete
  32 # the provisions above, a recipient may use your version of this file under
  33 # the terms of any one of the MPL, the GPL or the LGPL.
  34 #
  35 # ***** END LICENSE BLOCK *****
  36
  37
  38 // An Alarm fires a callback after a certain amount of time, or at
  39 // regular intervals. It's a convenient replacement for
  40 // setTimeout/Interval when you don't want to bind to a specific
  41 // window.
  42 //
  43 // The ConditionalAlarm is an Alarm that cancels itself if its callback
  44 // returns a value that type-converts to true.
  45 //
  46 // Example:
  47 //
  48 //  function foo() { dump('hi'); };
  49 //  new G_Alarm(foo, 10*1000);                   // Fire foo in 10 seconds
  50 //  new G_Alarm(foo, 10*1000, true /*repeat*/);  // Fire foo every 10 seconds
  51 //  new G_Alarm(foo, 10*1000, true, 7);          // Fire foo every 10 seconds
  52 //                                               // seven times
  53 //  new G_ConditionalAlarm(foo, 1000, true); // Fire every sec until foo()==true
  54 //
  55 //  // Fire foo every 10 seconds until foo returns true or until it fires seven
  56 //  // times, whichever happens first.
  57 //  new G_ConditionalAlarm(foo, 10*1000, true /*repeating*/, 7);
  58 //
  59 // TODO: maybe pass an isFinal flag to the callback if they opted to
  60 // set maxTimes and this is the last iteration?
  61
  62
  63 /**
  64  * Set an alarm to fire after a given amount of time, or at specific
  65  * intervals.
  66  *
  67  * @param callback Function to call when the alarm fires
  68  * @param delayMS Number indicating the length of the alarm period in ms
  69  * @param opt_repeating Boolean indicating whether this should fire
  70  *                      periodically
  71  * @param opt_maxTimes Number indicating a maximum number of times to
  72  *                     repeat (obviously only useful when opt_repeating==true)
  73  */
  74 function G_Alarm(callback, delayMS, opt_repeating, opt_maxTimes) {
  75   this.debugZone = "alarm";
  76   this.callback_ = callback;
  77   this.repeating_ = !!opt_repeating;
  78   this.timer_ = Cc["@mozilla.org/timer;1"].createInstance(Ci.nsITimer);
  79   var type = opt_repeating ?
  80              this.timer_.TYPE_REPEATING_SLACK :
  81              this.timer_.TYPE_ONE_SHOT;
  82   this.maxTimes_ = opt_maxTimes ? opt_maxTimes : null;
  83   this.nTimes_ = 0;
  84
  85   this.observerServiceObserver_ = new G_ObserverServiceObserver(
  86                                         'xpcom-shutdown',
  87                                         BindToObject(this.cancel, this));
  88
  89   // Ask the timer to use nsITimerCallback (.notify()) when ready
  90   this.timer_.initWithCallback(this, delayMS, type);
  91 }
  92
  93 /**
  94  * Cancel this timer
  95  */
  96 G_Alarm.prototype.cancel = function() {
  97   if (!this.timer_) {
  98     return;
  99   }
 100
 101   this.timer_.cancel();
 102   // Break circular reference created between this.timer_ and the G_Alarm
 103   // instance (this)
 104   this.timer_ = null;
 105   this.callback_ = null;
 106
 107   // We don't need the shutdown observer anymore
 108   this.observerServiceObserver_.unregister();
 109 }
 110
 111 /**
 112  * Invoked by the timer when it fires
 113  *
 114  * @param timer Reference to the nsITimer which fired (not currently
 115  *              passed along)
 116  */
 117 G_Alarm.prototype.notify = function(timer) {
 118   // fire callback and save results
 119   var ret = this.callback_();
 120
 121   // If they've given us a max number of times to fire, enforce it
 122   this.nTimes_++;
 123   if (this.repeating_ &&
 124       typeof this.maxTimes_ == "number"
 125       && this.nTimes_ >= this.maxTimes_) {
 126     this.cancel();
 127   } else if (!this.repeating_) {
 128     // Clear out the callback closure for TYPE_ONE_SHOT timers
 129     this.cancel();
 130   }
 131   // We don't cancel/cleanup timers that repeat forever until either
 132   // xpcom-shutdown occurs or cancel() is called explicitly.
 133
 134   return ret;
 135 }
 136
 137 G_Alarm.prototype.setDelay = function(delay) {
 138   this.timer_.delay = delay;
 139 }
 140
 141 /**
 142  * XPCOM cruft
 143  */
 144 G_Alarm.prototype.QueryInterface = function(iid) {
 145   if (iid.equals(Components.interfaces.nsISupports) ||
 146       iid.equals(Components.interfaces.nsITimerCallback))
 147     return this;
 148
 149   throw Components.results.NS_ERROR_NO_INTERFACE;
 150 }
 151
 152
 153 /**
 154  * An alarm with the additional property that it cancels itself if its
 155  * callback returns true.
 156  *
 157  * For parameter documentation, see G_Alarm
 158  */
 159 function G_ConditionalAlarm(callback, delayMS, opt_repeating, opt_maxTimes) {
 160   G_Alarm.call(this, callback, delayMS, opt_repeating, opt_maxTimes);
 161   this.debugZone = "conditionalalarm";
 162 }
 163
 164 G_ConditionalAlarm.inherits(G_Alarm);
 165
 166 /**
 167  * Invoked by the timer when it fires
 168  *
 169  * @param timer Reference to the nsITimer which fired (not currently
 170  *              passed along)
 171  */
 172 G_ConditionalAlarm.prototype.notify = function(timer) {
 173   // Call G_Alarm::notify
 174   var rv = G_Alarm.prototype.notify.call(this, timer);
 175
 176   if (this.repeating_ && rv) {
 177     G_Debug(this, "Callback of a repeating alarm returned true; cancelling.");
 178     this.cancel();
 179   }
 180 }