Runner

A Go module for executing time-based tasks with precise timing control.

Overview

Runner helps you execute recurring business logic that depends on specific timing requirements. The key principle is that task execution must be coordinated with real-time, ensuring tasks never run before their designated time.

Perfect for scenarios like:

• Processing log files at regular intervals
• Scheduled data aggregation
• Time-sensitive batch operations

Installation

go get github.com/marsgopher/runner

Key Concepts

Task Time vs Execution Time

• Task Time: The logical start time for the task (what time period the task should process)
• Execution Time: The actual time when the task runs (usually Task Time + delay)

Example Scenario

Consider a log processing system that runs every 5 minutes:

• Raw logs are generated every 5 minutes
• We need 30 minutes buffer to ensure logs are complete
• Task Time: 15:00 (process logs from 15:00-15:05)
• Execution Time: 15:35 (actual execution with 30min delay)

Configuration: Gap=30m, Interval=5m

Quick Start

Basic Usage

package main

import (
    "context"
    "fmt"
    "time"
    
    "github.com/marsgopher/runner"
)

func main() {
    // Create a runner with 5-minute intervals
    r := runner.New(runner.Config{
        Interval: 5 * time.Minute,
    })
    
    // Define your task
    task := func(ctx context.Context, taskTime time.Time) error {
        fmt.Printf("Processing data for: %s\n", taskTime.Format("15:04:05"))
        // Your business logic here
        return nil
    }
    
    // Run continuously
    r.Run(context.Background(), task)
}

With Custom Configuration

r := runner.New(runner.Config{
    Interval:  5 * time.Minute,   // Run every 5 minutes
    Gap:       30 * time.Minute,  // Wait 30 minutes after task time
    BeginTime: time.Now(),        // Start from now
})

Configuration

Each package provides a Config struct with options:

• Interval: Time between tasks
• Gap: Delay between task time and execution time
• BeginTime: When to start the first task
• EndTime: When to stop (optional)

Packages

intervalrun

Core package for interval-based task execution.

dailyrun

Execute tasks once per day with date-based logic.

gaprun

Handle tasks with specific gap requirements between task time and execution time.

Examples

Check out the examples directory for complete usage patterns:

• Continuous execution: runner-run
• Time range execution: runner-run-time-range
• Date range execution: runner-run-date-range
• Daily execution: dailyrun
• With hooks: runner-rundaily

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.