Why & How

The Philosophy of Kronos

Kronos was built out of the need for a simple, framework-agnostic persistent job scheduler in Kotlin. Existing options didn't fit the niche.

Does It Deliver on Its Promise?

The promise was: readable scheduling API, persistence across restarts, distributed safety, no framework lock-in.

Verdict: It delivers on its core promise with clear, documented tradeoffs. Sub-second precision is out of scope by design.

Advantages Over Cron

Disadvantages vs Cron

How It Fares Against Competitors

Efficiency

Tick flow

Every 60 seconds the runner fires a single indexed query:

-- MongoDB
db.jobs.find({ startTime: { $lte: now }, locks: 0 })

-- SQL
SELECT * FROM kronos_jobs WHERE start_time <= ? AND locks = 0

Both backends create a composite index on (start_time, locks) at initialization, so the query is a narrow index range scan over the due-job window rather than a full table scan.

For periodic jobs, the query returns all jobs whose startTime is in the past and whose locks counter is zero. A second validation pass in the runner then checks whether the job's calendar pattern (hour, minute, day-of-week, etc.) matches the current UTC minute before dispatching. This two-stage approach keeps the DB query simple while supporting complex periodic patterns in application code.

Read-path caching

findById, findAll, and findByName go through KacheController, which checks the cache (Redis or in-memory) first. The tick query (fetchDueJobs) bypasses the cache and always hits the DB — the 1-minute interval makes cache staleness a non-issue on the hot path, and the narrow indexed query is fast enough to not warrant caching.

Lock acquisition

Kronos uses a conditional atomic increment to prevent duplicate execution across instances:

-- MongoDB (atomic, single round-trip)
findOneAndUpdate({ _id: id, locks: 0 }, { $inc: { locks: 1 } })
→ returns the document before update, or null if locks ≠ 0

-- SQL
UPDATE kronos_jobs SET locks = locks + 1 WHERE id = ? AND locks = 0

On the MongoDB backend, acquireLock returns null when another instance already holds the lock — execution aborts cleanly. On the SQL backend, the UPDATE is equally atomic, but the current implementation returns the job row regardless of whether the update was applied, meaning the null-check guard in the runner is ineffective under contention. This is a known gap (see below).

The lock is never released. It functions as a one-shot execution marker: a job with locks > 0 is permanently skipped by the runner, then dropped after execution completes.

Resource profile

Measured against the MongoDB backend with a Redis cache, 100 concurrent trivial jobs (500 ms delay, no allocations), JVM max heap 2 GB:

The ~17 MB delta between idle and 100 concurrent jobs reflects coroutines' low per-task overhead — a thread-based scheduler would consume roughly 1 MB of stack space per concurrent task. Real-world peaks depend on how much each job allocates during execution.

The idle footprint (~50 MB) is driven by the MongoDB and Redis driver initialization, not Kronos itself. For containerised deployments, -Xmx128m is a safe floor for most workloads. Connection pool size is controlled by your MongoDB driver or DataSource configuration — Kronos does not manage it directly.

Known Gaps

• No backpressure: If a tick returns 10 000 due jobs, all are dispatched concurrently via supervisorScope. There is no concurrency cap or worker pool. Mitigation: use endTime or maxCycles to bound job volume, or batch scheduling on the application side.

• No retry backoff: Retries fire in a tight loop with no delay. A job that always fails burns a full DB round-trip per retry within the same tick. Planned: configurable fixed or exponential backoff.

• SQL locking gap: ExposedKronosStore.acquireLock performs an atomic conditional UPDATE but then unconditionally SELECTs and returns the row, so it can return a non-null result even when the lock was not acquired. Under concurrent load on the SQL backend, two instances could execute the same job. The MongoDB backend does not have this issue. Fix planned.

• InMemoryKronosStore missing: No in-process store exists for unit tests. Tests currently require Testcontainers (real MongoDB + Redis). Planned.

Comments