Refactor chrome.alarms interface to support absolute alarm deadlines.

chrome/common/extensions/api/alarms.idl

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // File-level comment to appease parser. Eventually this will not be necessary.
 // TODO(mpcomplete): We need documentation before we can release this.
 
 namespace alarms {
   dictionary Alarm {
     // Name of this alarm.
     DOMString name;
 
-    // Original length of time in minutes after which the onAlarm event should
-    // fire.
-    // TODO: need minimum=0
-    double delayInMinutes;
+    // Time at which this alarm was scheduled to fire, in milliseconds past the
+    // epoch (e.g. Date.now() + n).  For performance reasons, the alarm may have
+    // been delayed an arbitrary amount beyond this.
+    double scheduledTime;
 
-    // True if the alarm repeatedly fires at regular intervals, false if it
-    // only fires once.
-    boolean repeating;
+    // If not null, the alarm was re-scheduled 'repeatAfterMinutes' minutes
+    // after it fired.
+    double? repeatAfterMinutes;

[Aaron Boodman, 2012/06/09 04:21:10]

What is the purpose of this property?

[Jeffrey Yasskin, 2012/06/11 19:28:36]

Checking whether it's set at all replaces the 'repeating' property. Its value
used to be in the 'delayInMinutes', but since that's now an absolute time, it
doesn't encode the period of the repetition anymore, so I've stuck that
information here.

   };
 
   // TODO(mpcomplete): rename to CreateInfo when http://crbug.com/123073 is
   // fixed.
   dictionary AlarmCreateInfo {
+    // Time at which the alarm should fire, in milliseconds past the epoch
+    // (e.g. Date.now() + n).  Note that granularity is not guaranteed: this
+    // value is more of a hint to the browser. For performance reasons, alarms
+    // may be delayed an arbitrary amount of time before firing.
+    //
+    // This option may not be set if delayInMinutes is set or

[Aaron Boodman, 2012/06/09 04:21:10]

How about just creating two methods: createOneShot() and createRepeating().

[Jeffrey Yasskin, 2012/06/11 19:28:36]

Sure. How's this look?

+    // repeating is true.
+    double? approxTimeToFire;

[Aaron Boodman, 2012/06/09 04:21:10]

I don't think the 'approx' qualifier is needed. That is implied by the
conceptual purpose of the API and can be explained in the comments.

[Jeffrey Yasskin, 2012/06/11 19:28:36]

Done.

+
     // Length of time in minutes after which the onAlarm event should fire.
     // Note that granularity is not guaranteed: this value is more of a hint to
     // the browser. For performance reasons, alarms may be delayed an arbitrary
     // amount of time before firing.
+    //
+    // This option may not be set if approxTimeToFire is set.
+    //
     // TODO: need minimum=0
-    double delayInMinutes;
+    double? delayInMinutes;
 
     // True if the alarm should repeatedly fire at regular intervals. Defaults
     // to false.
     boolean? repeating;
   };
 
   callback AlarmCallback = void (Alarm alarm);
   callback AlarmListCallback = void (Alarm[] alarms);
 
   interface Functions {
@@ skipping 18 matching lines @@
     // Clears all alarms.
     static void clearAll();
   };
 
   interface Events {
     // Fired when an alarm has elapsed. Useful for transient background pages.
     // |alarm|: The alarm that has elapsed.
     static void onAlarm(Alarm alarm);
   };
 };