service

Documentation

Overview

Package service defines types and interfaces for long-running services that can be started and shut down.

TODO(a.garipov): Add tests.

Index

• Constants
• type Empty
  • func (Empty) Shutdown(_ context.Context) (err error)
  • func (Empty) Start(_ context.Context) (err error)
• type Interface
• type SignalHandler
  • func NewSignalHandler(c *SignalHandlerConfig) (h *SignalHandler)
  • func (h *SignalHandler) Add(svcs ...Interface)
  • func (h *SignalHandler) Handle(ctx context.Context) (status osutil.ExitCode)
• type SignalHandlerConfig

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.

Types

type Empty

type Empty struct{}

Empty is an Interface implementation that does nothing and returns nil.

func (Empty) Shutdown

func (Empty) Shutdown(_ context.Context) (err error)

Shutdown implements the Interface interface for Empty.

func (Empty) Start

func (Empty) Start(_ context.Context) (err error)

Start implements the Interface interface for Empty.

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)

	// 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)
}

Interface is the interface for long-running services.

type SignalHandler

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

SignalHandler processes incoming signals and shuts services down.

TODO(a.garipov): Expand to Windows.

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.