Kathikon (καθήκον — duty, obligation) is a BEAM-native durable job queue for Elixir. Jobs are persisted in Mnesia, executed by OTP supervisors and dispatchers, and tracked through an explicit state machine.
Current release: v0.2.0 — control, scheduling, batches, and correctness
Guides
Start here if you are new to the library:
| Guide | What you will learn |
|---|---|
| Quick start | Install, configure, define a worker, enqueue your first job |
| Workers | The Kathikon.Worker behaviour, return values, errors |
| Queues & concurrency | Multiple queues, dispatcher concurrency, isolation |
| Scheduling | schedule_in, schedule_at, cron, scheduler promotion |
| Retries & errors | Backoff, max_attempts, dead-letter, error recording |
| Cancellation | When jobs can be cancelled, API usage |
| Telemetry | Events, measurements, metadata, custom handlers |
| Configuration | All config :kathikon keys and environments |
| Storage & embedding | Mnesia setup, Livebook, tests, backends |
v0.2.0 topics
| Document | Contents |
|---|---|
| Storage | Storage behaviour, Mnesia tables, lifecycle |
| Job lifecycle | State machine and history events |
| Scheduling | One-time and recurring schedules, timezone |
| Batches | Fan-out/fan-in parent/child workflows |
| Management API | Claim, retry, dead-letter, queue control |
| Reporting | Queue and failure summaries |
| Quantum adapter | Optional Quantum scheduler integration |
| Architecture | Supervision tree and runtime components |
Reference
| Document | Contents |
|---|---|
| Module reference | Every module and public function with examples |
| Interactive demo | Livebook walkthrough |
Examples
Runnable scripts in examples/ at the project root — run with mix run examples/<name>.exs:
| Script | Demonstrates |
|---|---|
examples/basic_worker.exs | Insert and poll status |
examples/scheduled_job.exs | schedule with :at / :in |
examples/dead_letter_retry.exs | Failures, dead letter, rerun |
examples/batch_fanout_fanin.exs | Parent/child batches |
examples/reporting.exs | Kathikon.Report summaries |
examples/quantum_scheduler_adapter.exs | Optional Quantum scheduler |
Architecture at a glance
Kathikon.Supervisor
├── Registry
├── Kathikon.Queue (DynamicSupervisor → one Dispatcher per queue)
├── Kathikon.QueueControl
├── Kathikon.Scheduler.Promoter (promotes :scheduled → :available)
├── Kathikon.Scheduler.BuiltIn.Tick (cron evaluation, optional)
└── Kathikon.Pruner (deletes terminal jobs after retention)Public API: Kathikon.insert/3, Kathikon.schedule/3, Kathikon.cancel/1, Kathikon.fetch/1, Kathikon.status/1, Kathikon.history/1, Kathikon.all/0, Kathikon.start_queue/1, Kathikon.claim/2, Kathikon.retry/2, Kathikon.dead_jobs/1.