Documentation
¶
Overview ¶
Package service defines types and interfaces for long-running services that can be started and shut down.
Index ¶
- Constants
- type Empty
- type EmptyRefresher
- type ErrorHandler
- type ErrorHandlerFunc
- type IgnoreErrorHandler
- type Interface
- type RefreshWorker
- type RefreshWorkerConfig
- type Refresher
- type RefresherFunc
- type ShutdownService
- type Shutdowner
- type SignalHandler
- type SignalHandlerConfig
- type SlogErrorHandler
Examples ¶
Constants ¶
const SignalHandlerPrefix = "sighdlr"
SignalHandlerPrefix is the default and recommended prefix for the logger of a SignalHandler.
const SignalHandlerShutdownTimeout = 10 * time.Second
SignalHandlerShutdownTimeout is the default shutdown timeout for all services in a SignalHandler.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Empty ¶
type Empty struct{}
Empty is an Interface implementation that does nothing and returns nil.
type EmptyRefresher ¶ added in v0.31.2
type EmptyRefresher struct{}
EmptyRefresher is a Refresher that does nothing.
type ErrorHandler ¶ added in v0.31.2
type ErrorHandler interface {
// Handle handles the error. err must not be nil.
Handle(ctx context.Context, err error)
}
ErrorHandler is the interface for entities that handle errors from refreshes and other asyncrhonous jobs.
TODO(a.garipov): Consider moving to package errors.
type ErrorHandlerFunc ¶ added in v0.31.2
ErrorHandlerFunc is an adapter to allow the use of ordinary functions as [ErrorHandler]s.
func (ErrorHandlerFunc) Handle ¶ added in v0.31.2
func (f ErrorHandlerFunc) Handle(ctx context.Context, err error)
Handle implements the ErrorHandler interface for ErrorHandlerFunc.
type IgnoreErrorHandler ¶ added in v0.31.2
type IgnoreErrorHandler struct{}
IgnoreErrorHandler is a ErrorHandler that ignores all errors.
func (IgnoreErrorHandler) Handle ¶ added in v0.31.2
func (IgnoreErrorHandler) Handle(_ context.Context, _ error)
Handle implements the ErrorHandler interface for IgnoreErrorHandler.
type Interface ¶
type Interface interface {
// Start starts the service. ctx is used for cancelation.
//
// It is recommended that Start returns only after the service has
// completely finished its initialization. If that cannot be done, the
// implementation of Start must document that.
Start(ctx context.Context) (err error)
Shutdowner
}
Interface is the interface for long-running services.
func NewShutdownService ¶ added in v0.32.1
func NewShutdownService(s Shutdowner) (svc Interface)
NewShutdownService returns a properly initialized *ShutdownService. s must not be nil.
type RefreshWorker ¶ added in v0.31.2
type RefreshWorker struct {
// contains filtered or unexported fields
}
RefreshWorker is an Interface implementation that updates its Refresher every tick of the provided ticker.
func NewRefreshWorker ¶ added in v0.31.2
func NewRefreshWorker(c *RefreshWorkerConfig) (w *RefreshWorker)
NewRefreshWorker returns a new valid *RefreshWorker with the provided parameters. c must not be nil.
func (*RefreshWorker) Shutdown ¶ added in v0.31.2
func (w *RefreshWorker) Shutdown(ctx context.Context) (err error)
Shutdown implements the Interface interface for *RefreshWorker.
func (*RefreshWorker) Start ¶ added in v0.31.2
func (w *RefreshWorker) Start(ctx context.Context) (err error)
Start implements the Interface interface for *RefreshWorker. err is always nil.
If ctx has a logger added with slogutil.ContextWithLogger, that logger is used to report panics; otherwise, slog.Default is used to report them.
type RefreshWorkerConfig ¶ added in v0.31.2
type RefreshWorkerConfig struct {
// Clock is used for time-related operations of the refresher. If it is
// nil, [timeutil.SystemClock] is used.
Clock timeutil.ClockAfter
// ContextConstructor is used to provide a context for the Refresh method of
// Refresher. If it is nil, [contextutil.EmptyConstructor] is used.
ContextConstructor contextutil.Constructor
// ErrorHandler is used to handle the errors arising during the run of the
// worker. The passed context is the same context that has been passed to
// Refresh. If it is nil, [IgnoreErrorHandler] is used.
ErrorHandler ErrorHandler
// Refresher is the entity being refreshed. It must not be nil.
//
// The error returned by its Refresh method is returned from
// [RefreshWorker.Shutdown] only when
// [RefreshWorkerConfig.RefreshOnShutdown] is true. In all other cases,
// [RefreshWorkerConfig.ErrorHandler] is used.
Refresher Refresher
// Schedule defines when a refresher is run. Schedule.UntilNext is called
// after each refresh to determine how long the worker sleeps until the next
// refresh. It must not be nil.
Schedule timeutil.Schedule
// RefreshOnShutdown, if true, instructs the worker to refresh before
// shutting down the worker. This is useful for refreshers that use Refresh
// to persist to disk or remote storage before shutting down.
RefreshOnShutdown bool
}
RefreshWorkerConfig is the configuration structure for a *RefreshWorker.
type Refresher ¶ added in v0.31.2
type Refresher interface {
// Refresh is a method that is called to perform some kind of a job on an
// entity. Typically, this means updating some data or sending data
// somewhere else.
//
// See [RefreshWorker] for one of the uses.
Refresh(ctx context.Context) (err error)
}
Refresher is the interface for entities that can update themselves.
type RefresherFunc ¶ added in v0.31.2
RefresherFunc is an adapter to allow the use of ordinary functions as Refresher.
type ShutdownService ¶ added in v0.32.1
type ShutdownService struct {
// contains filtered or unexported fields
}
ShutdownService is an adapter for types that implement the Shutdowner interface but not the Interface one.
type Shutdowner ¶ added in v0.32.1
type Shutdowner interface {
// Shutdown gracefully stops the service. ctx is used to determine a
// timeout before trying to stop the service less gracefully.
//
// It is recommended that Shutdown returns only after the service has
// completely finished its termination. If that cannot be done, the
// implementation of Shutdown must document that.
Shutdown(ctx context.Context) (err error)
}
Shutdowner is the interface for types that have a Shutdown method but not necessarily a Start method.
type SignalHandler ¶
type SignalHandler struct {
// contains filtered or unexported fields
}
SignalHandler processes incoming signals and shuts services down.
func NewSignalHandler ¶
func NewSignalHandler(c *SignalHandlerConfig) (h *SignalHandler)
NewSignalHandler returns a new properly initialized *SignalHandler that shuts down services. If c is nil, the defaults of SignalHandlerConfig are used.
func (*SignalHandler) Add ¶
func (h *SignalHandler) Add(svcs ...Interface)
Add adds a services to the signal handler.
It must not be called concurrently with [Handle].
func (*SignalHandler) Handle ¶
func (h *SignalHandler) Handle(ctx context.Context) (status osutil.ExitCode)
Handle processes signals from the handler's osutil.SignalNotifier. It blocks until a termination signal is received, after which it shuts down all services. ctx is used for logging and serves as the base for the shutdown timeout. status is osutil.ExitCodeSuccess on success and osutil.ExitCodeFailure on error.
Handle must not be called concurrently with [Add].
type SignalHandlerConfig ¶
type SignalHandlerConfig struct {
// SignalNotifier is used to notify the handler about signals.
//
// If nil, [osutil.DefaultSignalNotifier] is used.
SignalNotifier osutil.SignalNotifier
// Logger is used for logging the shutting down of services. It should
// include a prefix; the recommended prefix is [SignalHandlerPrefix].
//
// If nil, [slog.Default] with [SignalHandlerPrefix] is used.
Logger *slog.Logger
// ShutdownTimeout is the timeout used to shut down all services gracefully.
//
// If zero, [DefaultShutdownTimeout] is used.
ShutdownTimeout time.Duration
}
SignalHandlerConfig contains the configuration for a signal handler. See NewSignalHandler.
type SlogErrorHandler ¶ added in v0.31.2
type SlogErrorHandler struct {
// contains filtered or unexported fields
}
SlogErrorHandler logs errors.
Example ¶
package main
import (
"context"
"log/slog"
"github.com/AdguardTeam/golibs/errors"
"github.com/AdguardTeam/golibs/logutil/slogutil"
"github.com/AdguardTeam/golibs/service"
)
func main() {
logger := slogutil.New(&slogutil.Config{
Format: slogutil.FormatJSON,
})
h := service.NewSlogErrorHandler(logger, slog.LevelError, "test message")
h.Handle(context.Background(), errors.Error("test error"))
}
Output: {"level":"ERROR","msg":"test message","err":"test error"}
func NewSlogErrorHandler ¶ added in v0.31.2
NewSlogErrorHandler returns a new logging error handler. l and lvl must not be nil.
func (*SlogErrorHandler) Handle ¶ added in v0.31.2
func (h *SlogErrorHandler) Handle(ctx context.Context, err error)
Handle implements the ErrorHandler interface for *SlogErrorHandler.
Source Files