executor

Documentation

Index

• Constants
• Variables
• func Multi(ctx context.Context, execs ...Executor) error
• func WithLocation(loc *time.Location) 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 WithRunners(runners ...Runner) cfg.Option[Config]
• func WithSchedule(cronString string) cfg.Option[Config]
• func WithScheduler(sched schedule.Scheduler) cfg.Option[Config]
• func WithTrace(tracer trace.Tracer) cfg.Option[Config]
• type Config
• type Executable
  • func (e Executable) Exec(ctx context.Context) error
  • func (e Executable) ID() string
  • func (e Executable) Next(ctx context.Context) time.Time
• type Executor
  • func AddLogs(e Executor, handler slog.Handler) Executor
  • func AddMetrics(e Executor, m Metrics) Executor
  • func AddTraces(e Executor, tracer trace.Tracer) Executor
  • func New(id string, options ...cfg.Option[Config]) (Executor, error)
  • func NoOp() Executor
• type Metrics
• type Runnable
  • func (r Runnable) Run(ctx context.Context) error
• type Runner

Constants

const (
	ErrEmpty = errs.Kind("empty")

	ErrRunnerList = errs.Entity("runners list")
	ErrScheduler  = errs.Entity("scheduler")
)

Variables

var (
	ErrEmptyRunnerList = errs.WithDomain(errDomain, ErrEmpty, ErrRunnerList)
	ErrEmptyScheduler  = errs.WithDomain(errDomain, ErrEmpty, ErrScheduler)
)

Functions

func Multi

func Multi(ctx context.Context, execs ...Executor) error

Multi calls the Executor.Exec on a set of Executor that are meant to be executed at the same time (e.g. when scheduled for the same time).

This call will execute the input (set of) action(s) in parallel, collecting any error(s) that the Executor(s) raises.

The returned error is a joined error, for any failing executions. The executions are synchronized in a sync.WaitGroup, and are bound to the input context.Context's lifetime.

func WithLocation

func WithLocation(loc *time.Location) cfg.Option[Config]

WithLocation configures the Executor's schedule.Scheduler with the input time.Location.

This call returns a cfg.NoOp cfg.Option if the input time.Location is nil.

Using this option implies using the WithSchedule option, as it means the caller is creating a schedule from a cron string, instead of passing a schedule.Scheduler with the WithScheduler option.

func WithLogHandler

func WithLogHandler(handler slog.Handler) cfg.Option[Config]

WithLogHandler decorates the Executor with logging using the input log handler.

func WithLogger

func WithLogger(logger *slog.Logger) cfg.Option[Config]

WithLogger decorates the Executor with the input logger.

func WithMetrics

func WithMetrics(m Metrics) cfg.Option[Config]

WithMetrics decorates the Executor with the input metrics registry.

func WithRunners

func WithRunners(runners ...Runner) cfg.Option[Config]

WithRunners configures the Executor with the input Runner(s).

This call returns a cfg.NoOp cfg.Option if no runners are provided, or if the ones provided are all nil. Any nil Runner or Runnable will be ignored.

func WithSchedule

func WithSchedule(cronString string) cfg.Option[Config]

WithSchedule configures the Executor with a schedule.Scheduler using the input cron string.

This call returns a cfg.NoOp cfg.Option if the cron string is empty.

This option can be followed by a WithLocation option.

func WithScheduler

func WithScheduler(sched schedule.Scheduler) cfg.Option[Config]

WithScheduler configures the Executor with the input schedule.Scheduler.

This call returns a cfg.NoOp cfg.Option if the input schedule.Scheduler is either nil or a no-op.

Using this option does not require passing WithSchedule nor WithLocation options.

func WithTrace

func WithTrace(tracer trace.Tracer) cfg.Option[Config]

WithTrace decorates the Executor with the input trace.Tracer.

Types

type Config

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

type Executable

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

Executable is an implementation of the Executor interface. It uses a schedule.Scheduler to mark the next job's execution time, and supports multiple Runner.

func (Executable) Exec

func (e Executable) Exec(ctx context.Context) error

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.

func (Executable) ID

func (e Executable) ID() string

ID returns this Executor's ID.

func (Executable) Next

func (e Executable) Next(ctx context.Context) time.Time

Next calls the Executor's underlying schedule.Scheduler Next method.

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) error
	// Next calls the Executor's underlying schedule.Scheduler Next method.
	Next(ctx context.Context) time.Time
	// 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.

func AddLogs

func AddLogs(e Executor, handler slog.Handler) Executor

AddLogs decorates the input Executor with logging, using the input slog.Handler.

If the input Executor is nil or a no-op Executor, a no-op Executor is returned. If the input slog.Handler is nil or a no-op handler, then a default slog.Handler is configured (a text handler printing to standard-error)

If the input Executor is already a logged Executor, then this logged Executor is returned with the new handler as its logger's handler.

Otherwise, the Executor is decorated with logging within a custom type that implements Executor.

func AddMetrics

func AddMetrics(e Executor, m Metrics) Executor

AddMetrics decorates the input Executor with metrics, using the input Metrics interface.

If the input Executor is nil or a no-op Executor, a no-op Executor is returned. If the input Metrics is nil or if it is a no-op Metrics interface, then the input Executor is returned as-is.

If the input Executor is already a Executor with metrics, then this Executor with metrics is returned with the new Metrics interface configured in place of the former.

Otherwise, the Executor is decorated with metrics within a custom type that implements Executor.

func AddTraces

func AddTraces(e Executor, tracer trace.Tracer) Executor

AddTraces decorates the input Executor with tracing, using the input trace.Tracer.

If the input Executor is nil or a no-op Executor, a no-op Executor is returned. If the input trace.Tracer is nil, then the input Executor is returned as-is.

If the input Executor is already a Executor with tracing, then this Executor with tracing is returned with the new trace.Tracer configured in place of the former.

Otherwise, the Executor is decorated with tracing within a custom type that implements Executor.

func New

func New(id string, options ...cfg.Option[Config]) (Executor, error)

New creates an Executor with the input cfg.Option(s), also returning an error if raised.

The minimum requirements to create an Executor is to supply at least one Runner, be it an implementation of this interface or as a Runnable using the WithRunners option, as well as a schedule.Scheduler using the WithScheduler option -- alternatively, callers can simply pass a cron string directly using the WithSchedule option.

If an ID is not supplied, then the default ID of `cron.executor` is set.

func NoOp

func NoOp() Executor

NoOp returns a no-op Executor

type Metrics

type Metrics interface {
	// IncExecutorExecCalls increases the count of Exec calls, by the Executor.
	IncExecutorExecCalls(id string)
	// IncExecutorExecErrors increases the count of Exec call errors, by the Executor.
	IncExecutorExecErrors(id string)
	// ObserveExecLatency registers the duration of an Exec call, by the Executor.
	ObserveExecLatency(ctx context.Context, id string, dur time.Duration)
	// IncExecutorNextCalls increases the count of Next calls, by the Executor.
	IncExecutorNextCalls(id string)
}

Metrics describes the actions that register Executor-related metrics.

type Runnable

type Runnable func(ctx context.Context) error

Runnable is a custom type for any function that takes in a context.Context and returns an error. This type of function can be perceived as a Runner type. For that, this custom type will implement Runner by exposing a Run method that invokes the actual Runnable function.

func (Runnable) Run

func (r Runnable) Run(ctx context.Context) error

Run executes the job or task.

This call takes in a context.Context which may be used to denote cancellation or closure (e.g. with a timeout)

The returned error denotes the success state of the execution. A nil error means that the execution was successful, where a non-nil error must signal a failed execution.

type Runner

type Runner interface {
	// Run executes the job or task.
	//
	// This call takes in a context.Context which may be used to denote cancellation or closure (e.g. with a timeout)
	//
	// The returned error denotes the success state of the execution. A nil error means that the execution was successful,
	// where a non-nil error must signal a failed execution.
	Run(ctx context.Context) error
}

Runner describes a type that executes a job or task. It contains only one method, Run, that is called with a context as input and returns an error.

Implementations of Runner only need to comply with this method, where the logic within Run is completely up to the actual implementation. These implementations need to be aware of the state of the input context.Context, which may denote cancellation or closure (e.g. with a timeout).

The returned error denotes the success state of the execution. A nil error means that the execution was successful, where a non-nil error must signal a failed execution.