Documentation
¶
Index ¶
- Constants
- Variables
- func JoinSchedules(execs []Executor) ([]Executor, []Executor)
- func NewClock() realClock
- func NoOp() noOpSelector
- func WithClock(clock Clock) cfg.Option[*Config]
- func WithExecutors(executors ...Executor) cfg.Option[*Config]
- func WithLogHandler(handler slog.Handler) cfg.Option[*Config]
- func WithLogger(logger *slog.Logger) cfg.Option[*Config]
- func WithMetrics(m Metrics) cfg.Option[*Config]
- func WithTimeout(dur time.Duration) cfg.Option[*Config]
- func WithTrace(tracer trace.Tracer) cfg.Option[*Config]
- type BlockingSelector
- type Clock
- type Config
- type Executor
- type Metrics
- type Selector
Constants ¶
const ( ErrEmpty = errs.Kind("empty") ErrExecutorsList = errs.Entity("executors list") )
Variables ¶
var ErrEmptyExecutorsList = errs.WithDomain(errSelectorDomain, ErrEmpty, ErrExecutorsList)
Functions ¶
func JoinSchedules ¶ added in v3.1.0
func WithClock ¶ added in v3.1.0
WithClock configures the selector with a Clock implementation that returns the current time, real or otherwise.
If unset, the Selector or BlockingSelector is configured with a real clock implementation using the standard library's time.Now call.
func WithExecutors ¶
WithExecutors configures the Selector with the input executor.Executor(s).
This call returns a cfg.NoOp cfg.Option if the input set of executor.Executor is empty, or contains only nil and / or no-op executor.Executor.
func WithLogHandler ¶
WithLogHandler decorates the Selector with logging using the input log handler.
func WithLogger ¶
WithLogger decorates the Selector with the input logger.
func WithMetrics ¶
WithMetrics decorates the Selector with the input metrics registry.
func WithTimeout ¶
WithTimeout configures a (non-blocking) Selector to wait a certain duration before detaching of the executable task, before continuing to select the next one.
By default, the local context timeout is set to one second. Any negative or zero duration values result in a cfg.NoOp cfg.Option being returned.
Types ¶
type BlockingSelector ¶
type BlockingSelector struct {
// contains filtered or unexported fields
}
func NewBlockingSelector ¶
func NewBlockingSelector(options ...cfg.Option[*Config]) (*BlockingSelector, error)
func (*BlockingSelector) Error ¶ added in v3.1.0
func (s *BlockingSelector) Error() error
func (*BlockingSelector) Next ¶
func (s *BlockingSelector) Next(ctx context.Context) error
Next picks up the following scheduled job to execute from its configured (set of) executor.Executor, and calls its Exec method.
This call also imposes a minimum step duration of 50ms, to ensure that early-runs are not executed twice due to the nature of using clocks in Go. This sleep is deferred to come in after the actual execution of the job.
The Selector allows multiple executor.Executor to be configured, and multiple executor.Executor can share similar execution times. If that is the case, the executor is launched in an executor.Multi call.
The error returned from a Next call is the error raised by the executor.Executor's Exec call.
func (*BlockingSelector) Stop ¶ added in v3.1.0
func (s *BlockingSelector) Stop() error
type Executor ¶
type Executor interface {
// Exec runs the task when on its scheduled time.
//
// For this, Exec leverages the Executor's underlying schedule.Scheduler to retrieve the job's next execution time,
// waits for it, and calls Runner.Run on each configured Runner. All raised errors are joined and returned at the end
// of this call.
Exec(ctx context.Context, now time.Time) error
// Next calls the Executor's underlying schedule.Scheduler Next method.
Next(ctx context.Context, now time.Time) time.Duration
// ID returns this Executor's ID.
ID() string
}
Executor describes the capabilities of cron job's executor component, which is based on fetching the next execution's time, Next; as well as running the job, Exec. It also exposes an ID method to allow access to this Executor's configured ID or name.
Implementations of Executor must focus on the logic of the Exec method, which should contain the logic of the Next method as well. It should not be the responsibility of other components to wait until it is time to execute the job; but actually the Executor's responsibility to consider it in its Exec method. That being said, its Next method (just like its ID method) allows access to some of the details of the executor if the caller needs that information; as helpers.
The logic behind Next and generally calculating the time for the next job execution should be deferred to a schedule.Scheduler, which should be part of the Executor.
One Executor may contain multiple Runner, as a job may be composed of several (smaller) tasks. However, an Executor is identified by a single ID.
type Metrics ¶
type Metrics interface {
// IncSelectorSelectCalls increases the count of Select calls, by the Selector.
IncSelectorSelectCalls(ctx context.Context)
// IncSelectorSelectErrors increases the count of Select call errors, by the Selector.
IncSelectorSelectErrors(ctx context.Context)
}
Metrics describes the actions that register Selector-related metrics.
type Selector ¶
type Selector struct {
// contains filtered or unexported fields
}
func New ¶
New creates a Selector with the input cfg.Option(s), also returning an error if raised.
Creating a Selector requires at least one executor.Executor, which can be added through the WithExecutors option. To allow this configuration to be variadic as well, it is served as a cfg.Option.
func (*Selector) Error ¶ added in v3.1.0
Error will return any stored errors in the Selector, with a swap-with-nil approach, resetting the errors stored in the Selector.
Errors are collected asynchronously and joined.
func (*Selector) Next ¶
Next complies with the common selector interface, which would run a (set of) executors and return an error if raised.
In an async approach, this method call will simply wait for the configured timeout duration and return the error(s) collected by its Selector.Error method call.
Callers of Selector.Next should consider to use Selector.Error directly, instead.
Source Files