// only executes one action at once. keeps track of
// optimal timestamps though, so actions may pile up.
// frequency may be set to 0 or even very close to zero
// (both values effectively stop the timer).
// persists frequency only
sclass FlexibleRateTimer implements AutoCloseable {
  double hertz;
  transient Runnable action;
  transient double timestamp;
  transient DoLater doLater;
  transient new Flag started;
  transient volatile bool disposed;
  transient long delay; // how much are we currently delayed
  transient L<Runnable> onFrequencyChanged;
  transient bool verbose;

  // below actualMinHertz, we stop the timer
  static double minHertz = 0, actualMinHertz = 1e-8, maxHertz = 1000;
  
  *() {}
  *(double *hertz) {}
  *(double *hertz, Runnable *action) {}
  
  void start {
    if (!started.raise()) ret;
    if (verbose) print("Starting timer with " + hertz + " Hz");
    _kaboom();
  }
  
  synchronized void _kaboom() pcall {
    if (verbose) print(disposed ? "Timer kaboom (disposed)" : "Timer kaboom");
    if (disposed) ret;
    dispose doLater;
    if (hertz <= actualMinHertz) ret with timestamp = 0;
    if (timestamp == 0) timestamp = sysNow();
    timestamp += 1000/getFrequency();
    long _timestamp = lround(timestamp);
    doLater = new DoLater(_timestamp, r {
      delay = sysNow()-_timestamp;
      if (verbose) print("Timer action");
      pcallF(action);
      _kaboom();
    });
    if (verbose) print("Timer scheduled for: " + (_timestamp-sysNow()));
    doLater.enable();
  }
  
  void cancel { close(); }
  
  public synchronized void close {
    set disposed;
    dispose doLater;
  }
  
  void setRunnableAndStart(Runnable action) {
    this.action = action;
    start();
  }
  
  // takes effect _after_ next trigger
  void setFrequency(double hertz) {
    synchronized(this) {
      if (disposed) ret;
      hertz = clamp(hertz, minHertz, maxHertz);
      if (hertz == this.hertz) ret;
      this.hertz = hertz;
    }
    pcallFAll(onFrequencyChanged);
  }
  
  // reschedule next action
  void setFrequencyImmediately(double hertz) {
    synchronized(this) {
      if (disposed) ret;
      hertz = clamp(hertz, minHertz, maxHertz);
      if (hertz == this.hertz) ret;
      this.hertz = hertz;
      if (!started.isUp()) ret;
      if (verbose) print("Timer setFreq doLater=" + doLater);
      bool b = doLater == null || doLater.cancel();
      print("Timer cancel result: " + b + " (" + this.hertz + " -> " + hertz + ")");
      timestamp = sysNow();
      if (b) _kaboom();
    }
    pcallFAll(onFrequencyChanged);
  }
  
  synchronized double getFrequency() { ret hertz; }
  
  long currentDelay() { ret delay; }
  
  synchronized void onFrequencyChanged(Runnable r) {
    onFrequencyChanged = addOrCreate(onFrequencyChanged,  r);
  }
  
  void onFrequencyChangedAndNow(Runnable r) {
    onFrequencyChanged(runAndReturn(r));
  }
}