idl/time.idl

   1 namespace Time;
   2
   3 struct Time inline {
   4         long seconds; // 0 is Jan 1, 1970 at midnight UTC; negative values
   5                       // can be used for historical dates or intervals
   6         uint nanos;   // Values greater than 999,999,999 are errors and
   7                       // should cause an exception to be thrown.
   8 };
   9
  10 struct ITime inline {
  11         Time value;
  12         Time interval;
  13 };
  14
  15 // A Clock will generally also implement TimerFactory and ITimerFactory,
  16 // producing timers that are tied to the clock in question.  The kernel
  17 // clock objects do not implement ITimerFactory.
  18
  19 interface Clock {
  20         guid: "C7F53E18-FD5C-11D9-B176-000A95BB581A";
  21
  22         // Get the current time according to this clock.
  23
  24         get_time(Time time out);
  25
  26         // Get the clock's resolution.  This is the largest
  27         // amount by which the clock may quantize its timekeeping.
  28
  29         get_resolution(Time res out);
  30
  31 };
  32
  33 // FIXME: Implement generic Factory
  34 interface TimerFactory {
  35         guid: "94BB5C90-41B6-11DA-8815-000A95BB581A";
  36         new_timer(Timer timer out);
  37 };
  38
  39 interface ITimerFactory {
  40         guid: "97C7A4DA-41B6-11DA-8615-000A95BB581A";
  41         new_itimer(ITimer itimer out);
  42 };
  43
  44 interface SettableClock {
  45         guid: "CED0AD0B-FD5C-11D9-954F-000A95BB581A";
  46
  47         // Set the clock's time.  This may be rounded off to no coarser
  48         // a precision than the clock's resolution.
  49
  50         set_time(Time time);
  51
  52         // Return a reference to the read-only Clock interface associated
  53         // with this object.
  54
  55         get_readonly_clock(Clock clock out);
  56 };
  57
  58 bitfield TimerFlags {
  59         // If set, set_time and get_time use Times relative to the current
  60         // time, rather than absolute time.
  61
  62         RelTime,
  63 };
  64
  65 interface Timer {
  66         guid: "F78C769F-146E-11DA-897A-000A95BB581A";
  67
  68         // Set/get the time at which this timer expires.
  69
  70         arm(Time expiry);
  71         get_expiry(Time expiry out, bool was_armed out);
  72
  73         // Stop the timer from firing.  This may be called regardless of
  74         // whether the timer is currently armed.  The timer is guaranteed to
  75         // not fire after the call completes, but may fire at any point during
  76         // the disarm() call.
  77         //
  78         // If the firing event is synchronous, it will have completed by the
  79         // time the disarm() call completes.  Otherwise, though the final
  80         // firing has happened, the handler may still be running after
  81         // disarm() returns.
  82
  83         disarm();
  84
  85         // Set the type of action to take when the timer fires.
  86
  87         set_action(Events.Event event);
  88 };
  89
  90 interface ITimer {
  91         guid: "D19B0A25-FD5C-11D9-9A2F-000A95BB581A";
  92
  93         // Arm the timer with the specified expiry.  If expiry.interval is not
  94         // zero, then when the timer expires, it will automatically be
  95         // re-armed with the time set to previous expiry plus the interval.
  96         // The previous expiry is atomically read and returned in oldexpiry.
  97         //
  98         // Nothing will happen on timer expiration unless an action has been
  99         // specified with set_action.
 100
 101         arm(ITime expiry, TimerFlags flags, ITime oldexpiry out);
 102
 103         // Return the expiry as with arm, but without setting a new
 104         // expiry.
 105
 106         get_expiry(TimerFlags flags, ITime expiry out, bool was_armed out);
 107
 108         // Disarm the timer.
 109
 110         disarm();
 111
 112         // Return the number of times since the last call to get_overrun
 113         // that a timer has fired without the previous timer action having
 114         // completed.
 115         //
 116         // For synchronous events such as a TrapEvent, this
 117         // includes the user trap handler not finishing on time (and in
 118         // such a case, new traps will not be generated for overrun firings).
 119         //
 120         // For asynchronous events such as a NotifierEvent, this only includes
 121         // the system's ability to send the notification.  If the user notify
 122         // method can't keep up, it will be reflected in a growing queue of
 123         // pending messages, not in the overrun count.
 124
 125         get_overrun(uint overruns out);
 126
 127         // Set the notifier to be used when the timer expires.  For kernel
 128         // timers, only sync instances of the kernel event dispatcher may be
 129         // used (the sync notifier may be a trigger for an async
 130         // NotifierEvent, though).
 131
 132         set_notifier(Notifiers.Notifier notifier);
 133         set_sync_notifier(Notifiers.SyncNotifier notifier);
 134 };