ticker.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (c) 2026 ForestHub. All rights reserved.
// For commercial licensing, visit https://github.com/ForestHubAI/fh-sdk
 
#ifndef FORESTHUB_UTIL_TICKER_HPP
#define FORESTHUB_UTIL_TICKER_HPP

 
namespace foresthub {
namespace util {

class Ticker {
public:
    explicit Ticker(unsigned long period, long offset = 0)
        : period_(period),
          offset_(offset),
          tz_offset_sec_(0),
          relative_(false),
          start_time_(0),
          last_slot_(0),
          fire_count_(0),
          missed_ticks_(0),
          max_fires_(0),
          running_(false) {}
 
    // -- Factory methods ------------------------------------------------------

    static Ticker Periodic(unsigned long interval) {
        Ticker t(interval);
        t.relative_ = true;
        return t;
    }

    static Ticker OneShot(unsigned long delay) {
        Ticker t = Periodic(delay);
        t.max_fires_ = 1;
        return t;
    }

    static Ticker Daily(int hour, int minute = 0) {
        return Ticker(86400UL, kEpochSundayOffset - (static_cast<long>(hour) * 3600L + minute * 60L));
    }

    static Ticker Weekly(int weekday, int hour, int minute = 0) {
        return Ticker(604800UL, kEpochSundayOffset - (static_cast<long>(weekday) * 86400L +
                                                      static_cast<long>(hour) * 3600L + minute * 60L));
    }

    static Ticker Hourly(int minute = 0) { return Ticker(3600UL, -(minute * 60L)); }
 
    // -- Builder --------------------------------------------------------------

    Ticker& WithMaxFires(unsigned long n) {
        max_fires_ = n;
        return *this;
    }

    Ticker& WithTimezoneOffset(long tz_offset_sec) {
        tz_offset_sec_ = tz_offset_sec;
        return *this;
    }
 
    // -- Lifecycle ------------------------------------------------------------

    void Start(unsigned long time) {
        if (relative_) {
            start_time_ = time;
        } else {
            last_slot_ = Slot(time);
        }
        fire_count_ = 0;
        missed_ticks_ = 0;
        running_ = true;
    }

    bool Check(unsigned long time) {
        if (!running_) return false;
 
        if (relative_) {
            // Wrap-safe unsigned path (immune to 32-bit unsigned overflow).
            unsigned long elapsed = time - start_time_;
            if (elapsed < period_) return false;
            missed_ticks_ = (elapsed / period_) - 1;
            start_time_ += (missed_ticks_ + 1) * period_;  // Drift correction: snap to grid.
        } else {
            // Slot-based path for calendar/epoch scheduling.
            long current_slot = Slot(time);
            if (current_slot <= last_slot_) return false;
            missed_ticks_ = static_cast<unsigned long>(current_slot - last_slot_ - 1);
            last_slot_ = current_slot;
        }
 
        ++fire_count_;
        if (max_fires_ > 0 && fire_count_ >= max_fires_) running_ = false;
        return true;
    }

    void Stop() { running_ = false; }

    void SetTimezoneOffset(long tz_offset_sec) { tz_offset_sec_ = tz_offset_sec; }
 
    // -- Getters --------------------------------------------------------------

    bool running() const { return running_; }

    unsigned long fire_count() const { return fire_count_; }

    unsigned long missed_ticks() const { return missed_ticks_; }

    unsigned long period() const { return period_; }

    long tz_offset_sec() const { return tz_offset_sec_; }
 
private:
    static constexpr long kEpochSundayOffset = 4L * 86400L;

    long Slot(unsigned long time) const {
        long val = static_cast<long>(time) + tz_offset_sec_ + offset_;
        long p = static_cast<long>(period_);
        return val / p - (val % p < 0);
    }
 
    unsigned long period_;
    long offset_;
    long tz_offset_sec_;  // Timezone offset in seconds (applied in Slot()).
    bool relative_;
    unsigned long start_time_;  // Reference time for relative mode (unsigned, wrap-safe).
    long last_slot_;            // Last computed slot for absolute mode (signed for negative slots).
    unsigned long fire_count_;
    unsigned long missed_ticks_;
    unsigned long max_fires_;
    bool running_;
};
 
}  // namespace util
}  // namespace foresthub
 
#endif  // FORESTHUB_UTIL_TICKER_HPP