tick

type Config ¶

type Config struct {
	// Interval is how often Pass runs.
	//
	// Zero or negative starts nothing, and is not an error: it is how an operator
	// says a cron job owns this. A caller with a default of its own resolves it
	// before it gets here, because there is no interval a library can pick for
	// somebody else's work.
	Interval time.Duration

	// Pass is one run.
	//
	// Called from one goroutine and never concurrently with itself, so it needs
	// no lock of its own against another pass — only against whatever else in the
	// process touches the same rows. It must not panic: nothing here may take a
	// process down over a pass that failed.
	//
	// A nil Pass starts nothing, the same as a zero Interval.
	Pass func(ctx context.Context)

	// PassTimeout bounds one pass. Zero is unbounded.
	//
	// Unbounded is the default because it is the answer that cannot be wrong.
	// Work that already declares its own deadline — a claim lease longer than
	// this interval, most often — would be cut off mid-write by a timeout set
	// here, and cut off *before* the statement that gives the claims back. Set
	// this only where the pass has no deadline of its own, and then the interval
	// is usually the number: a pass that cannot reach the database should fail
	// and be retried on the next tick rather than hold the slot forever.
	PassTimeout time.Duration
}

Config is what a Ticker needs.

type Ticker ¶

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

Ticker runs one pass on an interval and stops when it is told to.

The interesting part is not the ticker, which is six lines. It is the four properties around it, and every one of them is a bug somebody has already had in a hand-rolled version:

• Ticker.Start is idempotent, because two goroutines both closing the same `done` channel on the way out is a panic, in a shutdown path, from a goroutine that nothing is recovering.
• A Start after a Ticker.Close starts nothing, for the same reason.
• A Close with no prior Start returns immediately. Waiting on a goroutine that does not exist holds shutdown open for the whole registered timeout and then reports a failure — which is what an operator who left the work to a cron job and kept the shutdown registration has.
• A second Close, or two at once, is not a second close of a channel. The check and the close are under one lock, because as a check-then-act they are a race between two callers that both take the branch.

Close takes a context and returns an error so that it registers directly:

app.CloseWithin("notifications", 15*time.Second, engine.Close)

What it does not do is decide anything about the work. There is no error return from a pass, no backoff between passes, and no lease: a pass that fails is a pass, and the next one is coming. Anything that needs to be told apart from that belongs in Config.Pass, where the thing being done knows what it means.

Safe for concurrent use.

func New(cfg Config) *Ticker

func (t *Ticker) Close(ctx context.Context) error

func (t *Ticker) Nudge()

func (t *Ticker) Start()