// Author:  cirakg & claude ai
// Summary: Resumable jobs: long work split into small steps so no single event trips the watchdog.
//
// Connect IQ kills code that runs too long without returning to the system
// ("Watchdog Tripped"). The device files allow 120,000 bytecodes per event on
// the Forerunner 255/255S and 240,000 on the other targets; the simulator does
// not enforce this in test runs, so the only protection is design: anything
// that can take long (key derivation, SHA-512 batches, 2D barcode encoding,
// large imports) is a Job whose step() does a bounded amount of work.
//
// Steps are sized for the Forerunner 255/255S (the only 512 KB targets).
// Every 768 KB target allows twice as much per event
// (tools/gen_products.py --check fails if a product breaks that rule), so
// JobRunner runs two steps per tick there, which halves the time of an
// import or a large QR code.
//
// JobRunner drives a job from a timer and calls back when it is done.
// Tests call Jobs.runToCompletion() instead, synchronously.

import Toybox.Lang;
import Toybox.System;
import Toybox.Timer;

module Jobs {

    // Base class for resumable work.
    class Job {

        function initialize() {
        }

        // Do at most `budget` units of work. Returns true when the job is done.
        function step(budget as Number) as Boolean {
            return true;
        }
    }

    // Run a job to the end without yielding. Only for tests and work that is
    // known to be small.
    function runToCompletion(job as Job, budget as Number) as Void {
        while (!job.step(budget)) {
        }
    }

    // Drives a job from a timer: one step of `budget` units every TICK_MS.
    class JobRunner {

        // Pause between steps, so the UI stays responsive.
        static const TICK_MS = 50;

        private var _job as Job;
        private var _budget as Number;
        private var _onDone as Method() as Void;
        private var _timer as Timer.Timer?;

        function initialize(job as Job, budget as Number, onDone as Method() as Void) {
            _job = job;
            _budget = budget;
            _onDone = onDone;
        }

        // Start stepping; the first step runs on the first tick.
        function start() as Void {
            var timer = new Timer.Timer();
            timer.start(method(:onTick), TICK_MS, true);
            _timer = timer;
        }

        // Stop without finishing (for example, when the user leaves the screen).
        function cancel() as Void {
            var timer = _timer;
            if (timer != null) {
                timer.stop();
                _timer = null;
            }
        }

        function onTick() as Void {
            for (var i = 0; i < stepsPerTick(); i++) {
                if (_job.step(_budget)) {
                    cancel();
                    _onDone.invoke();
                    return;
                }
            }
        }
    }

    // App memory above this means a 240,000-bytecode watchdog.
    const LARGE_WATCH_MEMORY = 600000;
    var _stepsPerTick as Number = 0;

    // 1 on the 512 KB watches (120,000 bytecodes per event), 2 elsewhere.
    function stepsPerTick() as Number {
        if (_stepsPerTick == 0) {
            _stepsPerTick = System.getSystemStats().totalMemory > LARGE_WATCH_MEMORY ? 2 : 1;
        }
        return _stepsPerTick;
    }
}