cron

Documentation

Index

• type Action
• type Machine
  • func (m *Machine) Disable()
  • func (m *Machine) Enable()
  • func (m *Machine) OnScheduleChange()
  • func (m *Machine) OnTimerTick(tickNonce int64) error
  • func (m *Machine) RewindIfNecessary()
• type StartInvocationAction
  • func (a StartInvocationAction) IsAction() bool
• type State
  • func (s *State) Equal(o *State) bool
  • func (s *State) IsSuspended() bool
• type TickLaterAction
  • func (a *TickLaterAction) Equal(o *TickLaterAction) bool
  • func (a TickLaterAction) IsAction() bool

Types

type Action

type Action interface {
	IsAction() bool
}

Action is a particular action to perform when switching the state.

Can be type cast to some concrete *Action struct. Intended to be handled by whoever hosts the cron machine.

type Machine

type Machine struct {
	// Inputs.
	Now      time.Time          // current time
	Schedule *schedule.Schedule // knows when to emit invocation action
	Nonce    func() int64       // produces nonces on demand

	// Mutated.
	State   State    // state of the cron machine, mutated by its methods
	Actions []Action // all emitted actions (if any)
}

Machine advances the state of the cron machine.

It gracefully handles various kinds of external events (like pauses and schedule changes) and emits actions that's supposed to handled by whoever hosts it.

func (*Machine) Disable

func (m *Machine) Disable()

Disable stops any pending timer ticks, resets state.

The cron machine will ignore any events until Enable is called to turn it on.

func (*Machine) Enable

func (m *Machine) Enable()

Enable makes the cron machine start counting time.

Does nothing if already enabled.

func (*Machine) OnScheduleChange

func (m *Machine) OnScheduleChange()

OnScheduleChange happens when cron's schedule changes.

In particular, it handles switches between absolute and relative schedules.

func (*Machine) OnTimerTick

func (m *Machine) OnTimerTick(tickNonce int64) error

OnTimerTick happens when a scheduled timer tick (added with TickLaterAction) occurs.

Returns an error if the tick happened too soon.

func (*Machine) RewindIfNecessary

func (m *Machine) RewindIfNecessary()

RewindIfNecessary is called to restart the cron after it has fired the invocation action.

Does nothing if the cron is disabled or already ticking.

type StartInvocationAction

type StartInvocationAction struct {
	Generation int64 // value of state.Generation when the action was emitted
}

StartInvocationAction is emitted when the scheduled moment comes.

A handler is expected to call RewindIfNecessary() at some later time to restart the cron machine if it's running on a relative schedule (e.g. "with 10 sec interval"). Cron machines on relative schedules are "one shot". They need to be rewound to start counting time again.

Cron machines on absolute schedules (regular crons, like "at 12 AM every day") don't need rewinding, they'll start counting time until next invocation automatically. Calling RewindIfNecessary() for them won't hurt though, it will be noop.

func (StartInvocationAction) IsAction

func (a StartInvocationAction) IsAction() bool

IsAction makes StartInvocationAction implement Action interface.

type State

type State struct {
	// Enabled is true if the cron machine is running.
	//
	// A disabled cron machine ignores all events except 'Enable'.
	Enabled bool

	// Generation is increased each time state mutates.
	//
	// Monotonic, never resets. Should not be assumed sequential: some calls
	// mutate the state multiple times during one transition.
	//
	// Used to deduplicate StartInvocationAction in case of retries of cron state
	// transitions.
	Generation int64

	// LastRewind is a time when the cron machine was restarted last time.
	//
	// For relative schedules, it's a time RewindIfNecessary() was called. For
	// absolute schedules it is last time invocation happened (cron machines on
	// absolute schedules auto-rewind themselves).
	LastRewind time.Time

	// LastTick is last emitted tick request (or empty struct).
	//
	// It may be scheduled for "distant future" for paused cron machines.
	LastTick TickLaterAction
}

State stores serializable state of the cron machine.

Whoever hosts the cron machine is supposed to store this state in some persistent store between events. It's mutated by Machine. So the usage pattern is:

• Deserialize State, construct Machine instance with it.
• Invoke some Machine method (e.g Enable()) to advance the state.
• Acknowledge all actions emitted by the machine (see Machine.Actions).
• Serialize the mutated state (available in Machine.State).

If appropriate, all of the above should be done in a transaction.

Machine assumes that whoever hosts it handles TickLaterAction with following semantics:

• A scheduled tick can't be "unscheduled".
• A scheduled tick may come more than one time.

So the machine just ignores ticks it doesn't expect.

It supports "absolute" and "relative" schedules, see 'schedule' package for definitions.

func (*State) Equal

func (s *State) Equal(o *State) bool

Equal reports whether two structs are equal.

func (*State) IsSuspended

func (s *State) IsSuspended() bool

IsSuspended returns true if the cron machine is not waiting for a tick.

This happens for paused cron machines (they technically are scheduled for a tick in a distant future) and for cron machines on relative schedule that wait for 'RewindIfNecessary' to be called to start ticking again.

A disabled cron machine is also considered suspended.

type TickLaterAction

type TickLaterAction struct {
	When      time.Time
	TickNonce int64
}

TickLaterAction schedules an OnTimerTick call at given moment in time.

TickNonce is used by cron machine to skip canceled or repeated ticks.

func (*TickLaterAction) Equal

func (a *TickLaterAction) Equal(o *TickLaterAction) bool

Equal reports whether two structs are equal.

func (TickLaterAction) IsAction

func (a TickLaterAction) IsAction() bool

IsAction makes TickLaterAction implement Action interface.