TaskScheduler v2.0

Production-ready distributed task scheduling for Roblox with dual execution modes, priority queues, and automatic recovery.

Why TaskScheduler?

TaskScheduler provides production-ready background job processing:

• Flexibility: Choose at-least-once OR exactly-once per task
• Scalability: Server-level coordination for 100+ servers
• Reliability: Automatic retries, exponential backoff, and crash recovery
• Performance: Adaptive rate limiting prevents MessagingService overload
• Observability: Comprehensive statistics, hooks, and event logging
• Developer Experience: Simple API, configuration presets, and dependency tracking

What's New in v2.0

scheduler:SubmitTask({
    Name = "process_payment",
    ExactlyOnce = true, -- NEW!
    Payload = { amount = 1000 },
})

-- Small game (10-100 CCU)
local scheduler = TaskScheduler.newWithPreset("SMALL")

-- Large game (1000+ CCU, 20+ servers)
local scheduler = TaskScheduler.newWithPreset("LARGE")

Getting Started

Installation

Place TaskScheduler.lua in ReplicatedStorage.

Quick Start (Small Game)

local TaskScheduler = require(game.ReplicatedStorage.TaskScheduler)

-- Use preset for easy setup
local scheduler, preset = TaskScheduler.newWithPreset("SMALL", {
    PersistTasks = true,
    ObservabilityEnabled = true,
})

-- Create worker
local workerId = scheduler:CreateWorker({
    Handlers = {
        ["send_notification"] = function(task)
            local userId = task.Payload.userId
            local message = task.Payload.message
            
            print("Sending notification to", userId)
            -- Send logic here
            
            return true -- success
        end,
    },
})

-- Submit task
local taskId = scheduler:SubmitTask({
    Name = "send_notification",
    Priority = "high",
    Payload = {
        userId = 123,
        message = "Welcome!",
    },
})

-- Check status
local task = scheduler:GetTask(taskId)
print("Status:", task.Status)

Quick Start (Large Game - 1000+ CCU)

-- Optimized for 30+ servers
local scheduler, preset = TaskScheduler.newWithPreset("LARGE", {
    PersistTasks = true,
    ObservabilityEnabled = true,
    EnableExactlyOnce = true, -- for critical tasks
})

-- Create fewer workers with higher concurrency
scheduler:CreateWorker({
    MaxConcurrent = 15, -- higher than small games
    Handlers = {
        ["process_payment"] = function(task)
            -- Critical handler
            return true
        end,
        ["log_analytics"] = function(task)
            -- Non-critical handler
            return true
        end,
    },
})

-- Fast tasks: standard mode
scheduler:SubmitTask({
    Name = "log_analytics",
    Payload = { event = "player_joined" },
})

-- Critical tasks: exactly-once mode
scheduler:SubmitTask({
    Name = "process_payment",
    ExactlyOnce = true, -- guaranteed execution
    Payload = { amount = 1000 },
})

Execution Modes

TaskScheduler supports two execution modes. Choose the right one for each task type.

Standard Mode (Default)

scheduler:SubmitTask({
    Name = "send_notification",
    Priority = "normal",
    Payload = { ... },
    -- ExactlyOnce defaults to false
})

Characteristics

• At-least-once delivery (same as AWS SQS, Kafka, RabbitMQ)
• Zero coordination overhead
• Optimal performance for high-throughput workloads
• Tasks may execute multiple times under failure scenarios
• Handlers should be idempotent (industry best practice)

Best For

• Sending notifications (duplicate is harmless)
• Logging analytics (idempotent increment)
• Cache invalidation (safe to repeat)
• Background processing (95% of tasks)

Performance

• Latency: ~5-10ms
• Throughput: 1000s of tasks per second
• Overhead: None

Exactly-Once Mode (Optional)

scheduler:SubmitTask({
    Name = "process_payment",
    Priority = "critical",
    ExactlyOnce = true, -- Enable distributed locking
    Payload = { transactionId = "txn_123", amount = 1000 },
})

Characteristics

• Exactly-once execution guarantee via distributed locks
• Prevents duplicate processing across all servers
• Automatic lock acquisition and release
• Built-in deadlock prevention with TTL
• Slight latency overhead (~50-100ms)

How It Works

1. Worker acquires DataStore-based lock before execution
2. If lock is held by another server, task is skipped
3. Lock auto-extends during execution
4. Lock auto-releases on completion or timeout

Best For

• Processing payments (can't double-charge)
• Economy transactions (can't duplicate currency)
• Badge awards (want true deduplication)
• Critical operations (5% of tasks)

Performance

• Latency: ~50-100ms (lock overhead)
• Throughput: Same as standard mode
• Overhead: 2-3 DataStore operations per task

When to Use Each Mode

* For badge awards, you can use either mode with proper idempotency checks

Scaling Guide

TaskScheduler auto-scales with configuration presets. Choose based on your player count and server count.

Small Games (10-100 CCU, 1-5 servers)

local scheduler, preset = TaskScheduler.newWithPreset("SMALL", {
    PersistTasks = true,
})

Configuration

• Workers per server: 3
• Max concurrent per worker: 5
• Heartbeat interval: 5 seconds
• Poll interval: 0.5 seconds

Messaging Load

10 servers × 1 heartbeat every 5s = 2 publishes/sec

Medium Games (100-1000 CCU, 5-20 servers)

local scheduler, preset = TaskScheduler.newWithPreset("MEDIUM", {
    PersistTasks = true,
    ObservabilityEnabled = true,
})

Configuration

• Workers per server: 5
• Max concurrent per worker: 8
• Heartbeat interval: 10 seconds
• Poll interval: 0.5 seconds

Messaging Load

20 servers × 1 heartbeat every 10s = 2 publishes/sec

Large Games (1000+ CCU, 20+ servers)

local scheduler, preset = TaskScheduler.newWithPreset("LARGE", {
    PersistTasks = true,
    ObservabilityEnabled = true,
    EnableExactlyOnce = true, -- for critical tasks
})

Configuration

• Workers per server: 2-3 (fewer workers, higher concurrency each)
• Max concurrent per worker: 15
• Heartbeat interval: 15 seconds
• Poll interval: 1 second
• Adaptive rate limiting: Enabled

Messaging Load

50 servers × 1 heartbeat every 15s = 3.3 publishes/sec

100 servers × 1 heartbeat every 15s (with backoff) = ~4 publishes/sec

Scaling Comparison

Core Concepts

Tasks

A task is a unit of work with a name, payload, and configuration. Tasks move through states:

• pending: Queued, waiting for worker
• running: Currently executing
• completed: Successfully finished
• failed: Failed but will retry
• dead: Permanently failed (moved to dead letter queue)

Workers

Workers pull tasks from the queue and execute handler functions. Each worker:

• Runs up to MaxConcurrent tasks simultaneously
• Polls the queue at PollInterval
• Requests work stealing when underutilized
• Tracked by server-level heartbeat

Priority Levels

Tasks are executed in priority order:

1. critical: Urgent tasks (executed first)
2. high: Important tasks
3. normal: Default priority
4. low: Background tasks

API Reference

TaskScheduler.new

Creates a new task scheduler instance with custom configuration.

Config Options

TaskScheduler.newWithPreset

NEW v2.0 Creates a scheduler with preset configuration for easy scaling.

Presets

• "SMALL" - Small games (10-100 CCU, 1-5 servers)
• "MEDIUM" - Medium games (100-1000 CCU, 5-20 servers)
• "LARGE" - Large games (1000+ CCU, 20+ servers)
• "SINGLE_SERVER" - Testing / single server (disables messaging)

local scheduler, preset = TaskScheduler.newWithPreset("LARGE", {
    PersistTasks = true,
    EnableExactlyOnce = true,
})

print("Workers per server:", preset.workers)
print("Max concurrent:", preset.maxConcurrent)

CreateWorker

Creates a worker that executes tasks.

Config Options

SubmitTask

Submits a task to the queue.

Config Options

GetTask

Retrieves a task by ID. Returns nil if not found.

CancelTask

Cancels a pending task. Returns false if task is running or complete.

GetStats

Returns scheduler statistics.

Configuration

Recommended Configurations by Scale

Small Game

local scheduler = TaskScheduler.newWithPreset("SMALL", {
    PersistTasks = true,
})

Medium Game

local scheduler = TaskScheduler.newWithPreset("MEDIUM", {
    PersistTasks = true,
    ObservabilityEnabled = true,
})

Large Game

local scheduler = TaskScheduler.newWithPreset("LARGE", {
    PersistTasks = true,
    ObservabilityEnabled = true,
    EnableExactlyOnce = true,
})

Custom Configuration

local scheduler = TaskScheduler.new({
    PersistTasks = true,
    ObservabilityEnabled = true,
    EnableExactlyOnce = true,
    DeadLetterRetention = 172800, -- 48 hours
    CleanupInterval = 600, -- 10 minutes
    PersistenceBatchSize = 20,
})

Best Practices

1. Write Idempotent Handlers

Even with exactly-once mode, handlers should be idempotent:

-- GOOD: Idempotent handler
["award_badge"] = function(task)
    local userId = task.Payload.userId
    local badgeId = task.Payload.badgeId
    
    -- Check if already awarded
    local key = userId .. "_" .. badgeId
    if DataStore:GetAsync(key) then
        return true -- already done
    end
    
    -- Award badge
    BadgeService:AwardBadge(userId, badgeId)
    DataStore:SetAsync(key, true)
    
    return true
end

2. Use Exactly-Once Sparingly

-- Standard mode for most tasks (95%)
scheduler:SubmitTask({
    Name = "send_notification",
    Payload = { ... },
})

-- Exactly-once only for critical tasks (5%)
scheduler:SubmitTask({
    Name = "process_payment",
    ExactlyOnce = true,
    Payload = { ... },
})

3. Choose the Right Preset

-- Small game
local scheduler = TaskScheduler.newWithPreset("SMALL")

-- Large game (don't use SMALL preset!)
local scheduler = TaskScheduler.newWithPreset("LARGE")

4. Monitor Statistics

task.spawn(function()
    while true do
        task.wait(60)
        local stats = scheduler:GetStats()
        
        if stats.dead > 10 then
            warn("High dead letter count:", stats.dead)
        end
        
        if stats.pending > 500 then
            warn("Queue backlog detected:", stats.pending)
        end
    end
end)

Examples

Mixed Execution Modes

local scheduler = TaskScheduler.newWithPreset("MEDIUM", {
    EnableExactlyOnce = true,
})

scheduler:CreateWorker({
    Handlers = {
        ["log_analytics"] = function(task)
            -- Non-critical: standard mode is fine
            AnalyticsStore:IncrementAsync("events", 1)
            return true
        end,
        
        ["grant_currency"] = function(task)
            -- Critical: ensure idempotency
            local userId = task.Payload.userId
            local amount = task.Payload.amount
            
            -- Check if already granted
            local key = "currency_" .. task.Id
            if DataStore:GetAsync(key) then
                return true
            end
            
            -- Grant currency
            local profile = ProfileStore:LoadProfileAsync(userId)
            profile.Data.Currency += amount
            DataStore:SetAsync(key, true)
            
            return true
        end,
    },
})

-- Fast: standard mode
scheduler:SubmitTask({
    Name = "log_analytics",
    Payload = { event = "player_joined" },
})

-- Guaranteed: exactly-once mode
scheduler:SubmitTask({
    Name = "grant_currency",
    ExactlyOnce = true,
    Payload = { userId = 123, amount = 100 },
})

Dependency Chains

local task1 = scheduler:SubmitTask({
    Name = "fetch_data",
})

local task2 = scheduler:SubmitTask({
    Name = "process_data",
    DependsOn = {task1},
})

local task3 = scheduler:SubmitTask({
    Name = "save_results",
    DependsOn = {task2},
    ExactlyOnce = true, -- ensure final save is guaranteed
})

Scheduled Tasks

-- Daily reset at midnight
local midnight = os.time({
    year = 2026,
    month = 2,
    day = 17,
    hour = 0,
})

scheduler:SubmitTask({
    Name = "daily_reset",
    ScheduledFor = midnight,
    ExactlyOnce = true, -- ensure it only runs once
})

Performance

Throughput

Messaging Load by Scale

Adaptive backoff automatically adjusts intervals to stay under limits

v1.0 vs v2.0

Troubleshooting

Tasks Not Executing

Possible causes:

• No worker with matching handler
• All workers at MaxConcurrent limit
• Task has unmet dependencies
• Task is scheduled for future
• Exactly-once lock is held by another server

High Dead Letter Count

-- Inspect dead letters
for taskId, task in pairs(scheduler.DeadLetterQueue) do
    print("Failed:", task.Name)
    print("Error:", task.LastError)
    print("Attempts:", task.Attempts)
    print("ExactlyOnce:", task.ExactlyOnce)
end

MessagingService Rate Limits

If you see RateLimitBackoff events frequently:

• Use a larger preset (MEDIUM LARGE)
• Reduce worker count
• Adaptive backoff will handle it automatically

Exactly-Once Tasks Skipped

Check for TaskLockFailed events in observability logs. This means another server is already executing the task (working as intended).

Getting Help

• Enable ObservabilityEnabled for detailed logs
• Check task Status and LastError fields
• Monitor GetStats() output
• Contact @chi0sk on Discord