Documentation
¶
Overview ¶
Package libroutine runs recurring background tasks under circuit-breaker protection: Routine is the breaker, group manages one keyed loop per task, and Runner, Job and Schedule build condition-gated job chains on top of a Routine that can be fired directly, on a Schedule, or from a libbus subject.
Index ¶
- Variables
- func GetGroup() *group
- type Condition
- type Job
- type LoopConfig
- type Operation
- type Routine
- func (rm *Routine) Allow() bool
- func (rm *Routine) Execute(ctx context.Context, fn func(ctx context.Context) error) error
- func (rm *Routine) ExecuteWithRetry(ctx context.Context, interval time.Duration, iterations int, ...) error
- func (rm *Routine) ForceClose()
- func (rm *Routine) ForceOpen()
- func (rm *Routine) GetResetTimeout() time.Duration
- func (rm *Routine) GetState() State
- func (rm *Routine) GetThreshold() int
- func (rm *Routine) Loop(ctx context.Context, interval time.Duration, triggerChan <-chan struct{}, ...)
- func (rm *Routine) MarkFailure()
- func (rm *Routine) MarkSuccess()
- type RunResult
- type Runner
- func (r *Runner) Run(ctx context.Context) (*RunResult, error)
- func (r *Runner) Running() bool
- func (r *Runner) StartSchedule(ctx context.Context, sched Schedule)
- func (r *Runner) SubscribeMessenger(ctx context.Context, bus libbus.Messenger, subject string) (libbus.Subscription, error)
- func (r *Runner) Trigger(ctx context.Context)
- type RunnerOption
- type Schedule
- type State
Constants ¶
This section is empty.
Variables ¶
var ErrAlreadyRunning = errors.New("libroutine: job is already running")
ErrAlreadyRunning is returned by Run when the Runner's job chain is already executing.
var ErrCircuitOpen = errors.New("circuit breaker is open")
ErrCircuitOpen is returned by Execute when the circuit breaker is Open.
Functions ¶
Types ¶
type Condition ¶ added in v0.38.0
Condition gates whether a Job's Operation runs. A nil Condition on a Job always proceeds.
type Job ¶ added in v0.38.0
type Job struct {
// Name identifies this job in RunResult and error messages.
Name string
// Condition, if set, is evaluated before Operation. A false result skips
// Operation and Next without failing the run.
Condition Condition
Operation Operation
// Next, if set, runs after Operation succeeds.
Next *Job
}
Job is one step in a chain: check Condition, run Operation, and if both succeed continue into Next. A Job is driven by a Runner.
type LoopConfig ¶
type LoopConfig struct {
// Key uniquely identifies the routine and prevents duplicate loops.
Key string
// Threshold is the number of consecutive failures before the circuit opens.
Threshold int
// ResetTimeout is how long the circuit stays open before half-open.
ResetTimeout time.Duration
// Interval is the time between executions.
Interval time.Duration
// Operation is the function executed periodically.
Operation func(ctx context.Context) error
}
LoopConfig configures one managed background loop.
type Operation ¶ added in v0.38.0
Operation is the work a Job performs once its Condition allows it.
type Routine ¶
type Routine struct {
// contains filtered or unexported fields
}
Routine is a circuit breaker: it tracks failures, opens the circuit when a threshold is reached, and resets automatically after a timeout via HalfOpen.
func NewRoutine ¶
NewRoutine creates a Routine that opens after threshold consecutive failures and stays Open for resetTimeout before transitioning to HalfOpen.
func (*Routine) Allow ¶
Allow reports whether the circuit breaker permits an operation. It may transition the state from Open to HalfOpen if the reset timeout has passed.
func (*Routine) ExecuteWithRetry ¶
func (rm *Routine) ExecuteWithRetry(ctx context.Context, interval time.Duration, iterations int, fn func(ctx context.Context) error) error
ExecuteWithRetry runs fn via Execute, retrying on failure up to iterations times with a fixed interval between attempts. It returns the last error, or the context cause if ctx is cancelled.
func (*Routine) ForceClose ¶
func (rm *Routine) ForceClose()
ForceClose sets the circuit breaker to Closed and resets the failure count.
func (*Routine) ForceOpen ¶
func (rm *Routine) ForceOpen()
ForceOpen sets the circuit breaker to the Open state.
func (*Routine) GetResetTimeout ¶
GetResetTimeout returns the reset timeout duration configured for this circuit breaker.
func (*Routine) GetThreshold ¶
GetThreshold returns the failure threshold configured for this circuit breaker.
func (*Routine) Loop ¶
func (rm *Routine) Loop(ctx context.Context, interval time.Duration, triggerChan <-chan struct{}, fn func(ctx context.Context) error, errHandling func(err error))
Loop runs fn via Execute immediately, then on every interval tick or triggerChan signal, until ctx is cancelled. errHandling is called with each error, including ErrCircuitOpen.
func (*Routine) MarkFailure ¶
func (rm *Routine) MarkFailure()
MarkFailure records a failed operation, tripping the circuit to Open once the threshold is reached or a HalfOpen test fails.
func (*Routine) MarkSuccess ¶
func (rm *Routine) MarkSuccess()
MarkSuccess resets the circuit breaker after a successful call.
type RunResult ¶ added in v0.38.0
type RunResult struct {
Name string
Skipped bool
Err error
Duration time.Duration
// Next is the chained job's result, set only when Next was run.
Next *RunResult
}
RunResult reports the outcome of running a Job, including its chain.
type Runner ¶ added in v0.38.0
type Runner struct {
// contains filtered or unexported fields
}
Runner drives one Job's execution through a dedicated Routine, with a single-flight guard so a slow run is never overlapped by its own next trigger. It is safe for concurrent use.
func NewRunner ¶ added in v0.38.0
NewRunner returns a Runner for job, protected by a Routine constructed with threshold and resetTimeout. The job chain is not started.
func (*Runner) Run ¶ added in v0.38.0
Run executes the job chain synchronously through the Runner's Routine. It returns a nil result with ErrAlreadyRunning or ErrCircuitOpen when the chain is already executing or the circuit is open.
func (*Runner) Running ¶ added in v0.38.0
Running reports whether the job chain is currently executing.
func (*Runner) StartSchedule ¶ added in v0.38.0
StartSchedule runs r.Trigger each time sched fires, until ctx is cancelled. It returns immediately, and a tick that lands mid-run is dropped rather than queued.
func (*Runner) SubscribeMessenger ¶ added in v0.38.0
func (r *Runner) SubscribeMessenger(ctx context.Context, bus libbus.Messenger, subject string) (libbus.Subscription, error)
SubscribeMessenger triggers r every time a message is published to subject on bus. The subscription is torn down when ctx is done, or earlier via the returned Subscription.
type RunnerOption ¶ added in v0.38.0
type RunnerOption func(*Runner)
RunnerOption configures a Runner at construction.
func WithResultHook ¶ added in v0.38.0
func WithResultHook(fn func(*RunResult)) RunnerOption
WithResultHook registers fn to be called with the RunResult of every run that actually executed the job. fn is called synchronously and must not block.
func WithTracker ¶ added in v0.38.0
func WithTracker(tracker libtracker.ActivityTracker) RunnerOption
WithTracker wires an ActivityTracker to observe every Run. Without it, a Runner uses libtracker.NoopTracker.
type Schedule ¶ added in v0.38.0
Schedule computes the next run time after t. It is interface-compatible with robfig/cron/v3's cron.Schedule.