schedule

Documentation

Overview

Package schedule provides lifecycle-owned fixed-delay job execution for generated Spice applications.

Index

• Variables
• type Definition
• type Job
• type Observer
• type PanicError
  • func (err *PanicError) Error() string
  • func (err *PanicError) Unwrap() error
• type Result
• type Scheduler
  • func New(lifetime context.Context, jobs []Job, waiter Waiter, observers ...Observer) (*Scheduler, error)
  • func (scheduler *Scheduler) Done() <-chan struct{}
  • func (scheduler *Scheduler) Shutdown(ctx context.Context) error
  • func (scheduler *Scheduler) Snapshot() Snapshot
  • func (scheduler *Scheduler) Start(ctx context.Context) error
• type Snapshot
• type Waiter

Examples

• Scheduler

Variables

var (
	// ErrStarted identifies a duplicate scheduler start.
	ErrStarted = errors.New("scheduler is already started")
	// ErrClosed identifies a scheduler that has begun shutdown.
	ErrClosed = errors.New("scheduler is closed")
	// ErrPanicked identifies a contained scheduled-job panic.
	ErrPanicked = errors.New("scheduled job panicked")
)

Types

type Definition

type Definition struct {
	ID     string
	Module string
}

Definition identifies one compiler-owned job and its module.

type Job

type Job struct {
	Definition      Definition
	InitialDelay    time.Duration
	Delay           time.Duration
	ContinueOnError bool
	Run             func(context.Context) error
}

Job is one serial fixed-delay schedule. ContinueOnError must be explicitly selected when a failed run is safe to repeat.

type Observer

type Observer func(context.Context, Result)

Observer receives completed runs on the job goroutine.

type PanicError

type PanicError struct {
	Definition Definition
}

PanicError reports a contained scheduled-job panic without exposing the recovered value.

func (*PanicError) Error

func (err *PanicError) Error() string

Error describes the panicked job.

func (*PanicError) Unwrap

func (err *PanicError) Unwrap() error

Unwrap supports errors.Is(err, ErrPanicked).

type Result

type Result struct {
	Definition Definition
	Run        uint64
	Duration   time.Duration
	Err        error
	Panicked   bool
}

Result describes one completed scheduled run.

type Scheduler

type Scheduler struct {
	// contains filtered or unexported fields
}

Scheduler owns immutable jobs and one goroutine per started job.

Example

package main

import (
	"context"
	"fmt"
	"sync/atomic"
	"time"

	"github.com/spice-framework/spice/schedule"
)

func main() {
	lifetime, cancel := context.WithCancel(context.Background())
	var runs atomic.Uint64
	scheduler, err := schedule.New(lifetime, []schedule.Job{{
		Definition: schedule.Definition{
			ID:     "inventory.Refresh",
			Module: "example.com/shop/inventory",
		},
		Delay: time.Minute,
		Run: func(context.Context) error {
			runs.Add(1)
			cancel()
			return nil
		},
	}}, nil)
	if err != nil {
		fmt.Printf("construct: %v\n", err)
		return
	}
	err = scheduler.Start(context.Background())
	if err == nil {
		<-scheduler.Done()
		err = scheduler.Shutdown(context.Background())
	}
	fmt.Printf("runs=%d err=%v\n", runs.Load(), err)
}

Output:
runs=1 err=<nil>

func New

func New(
	lifetime context.Context,
	jobs []Job,
	waiter Waiter,
	observers ...Observer,
) (*Scheduler, error)

New constructs an inert scheduler. A nil waiter selects context-aware timers.

func (*Scheduler) Done

func (scheduler *Scheduler) Done() <-chan struct{}

Done closes when every started job exits, or immediately when an unstarted scheduler shuts down.

func (*Scheduler) Shutdown

func (scheduler *Scheduler) Shutdown(ctx context.Context) error

Shutdown stops future runs and lets current runs drain. If ctx ends first, current task contexts are canceled and Shutdown returns without waiting for jobs that ignore cancellation.

func (*Scheduler) Snapshot

func (scheduler *Scheduler) Snapshot() Snapshot

Snapshot returns aggregate scheduler state.

func (*Scheduler) Start

func (scheduler *Scheduler) Start(ctx context.Context) error

Start launches each immutable job once. Its context bounds only the start transition; job execution uses the lifetime supplied to New.

type Snapshot

type Snapshot struct {
	Jobs     int
	Runs     uint64
	Running  int
	Failed   uint64
	Panicked uint64
	Started  bool
	Closed   bool
}

Snapshot is a concurrency-safe scheduler view.

type Waiter

type Waiter func(context.Context, time.Duration) error

Waiter waits between runs. A nil Waiter uses a context-aware timer.