Features

This chapter covers the core features and capabilities of Task Scheduler.

Features

• Cron expressions — Full 5-field parser supporting *, */n, a-b, a,b,c, and combinations
• Interval scheduling — Run tasks every N seconds with drift-free tracking
• One-shot tasks — Fire once at a specified datetime, then never again
• Priority queue — Higher-priority tasks run first when multiple are due simultaneously
• Concurrency control — Cap the number of tasks running in parallel via thread semaphore
• Retry with backoff — Failed tasks retry up to N times with configurable exponential delay
• Missed-run policy — Choose catch_up (fire immediately on overdue) or skip (wait for next window)
• State persistence — Schedule state and last-run timestamps survive restarts via JSON file
• Built-in demo tasks — heartbeat, disk_usage, and cleanup_tmp for testing without shell commands
• Single-tick mode — --once runs one scheduler pass and exits (ideal for testing and cron-driven invocation)

Requirements

• Python 3.10+
• No external dependencies (stdlib only)

Quick Start

Follow this guide to get Task Scheduler up and running in your environment.

Quick Start

# Show all CLI options
python src/task_scheduler.py --help

# List tasks with their next scheduled fire times
python src/task_scheduler.py --config examples/task_scheduler_config.json --list

# Run a single scheduler tick (fires due tasks, then exits)
python src/task_scheduler.py --config examples/task_scheduler_config.json --once

# Start the daemon loop (Ctrl-C to stop)
python src/task_scheduler.py --config examples/task_scheduler_config.json

# Override state file location and log level
python src/task_scheduler.py --config examples/task_scheduler_config.json --state-file /tmp/state.json --log-level DEBUG

Configuration Reference

Create a JSON config to define your task schedule:

{
    "settings": {
        "max_concurrency": 3,
        "tick_interval": 1.0,
        "state_file": "scheduler_state.json"
    },
    "tasks": [
        {
            "name": "my-task",
            "schedule_type": "cron",
            "schedule_value": "*/5 * * * *",
            "command": "echo 'hello'",
            "priority": 3,
            "retry_limit": 2,
            "retry_backoff": 2.0,
            "missed_policy": "skip",
            "enabled": true
        }
    ]
}

CLI Options

Cron Syntax

Standard 5-field format: minute hour day-of-month month day-of-week

Operators: * (all), */n (step), a-b (range), a-b/n (range+step), a,b,c (list).

Task Fields