runners

README

go-runners

Provides a means a simple means of managing long-running functions and services

Documentation

Index

• func ContextWithCancel() (context.Context, context.CancelFunc)
• func GoRun(handOff time.Duration, fn func(ctx context.Context) error, ...) (func(), bool)
• func RetryGoRun(retries int, handOff time.Duration, fn func(ctx context.Context) error, ...) (func(), bool)
• func Run(fn func() error) (err error)
• type FuncRunner
  • func (r *FuncRunner) Err() error
  • func (r *FuncRunner) Go(fn func(ctx context.Context) error) bool
  • func (r *FuncRunner) Stop() bool
• type Service
  • func (svc *Service) Done() <-chan struct{}
  • func (svc *Service) Run(fn func(context.Context)) bool
  • func (svc *Service) Running() bool
  • func (svc *Service) Stop(fn func()) bool
  • func (svc *Service) Stopping() bool

Functions

func ContextWithCancel

func ContextWithCancel() (context.Context, context.CancelFunc)

ContextWithCancel returns a new context.Context impl with cancel.

func GoRun

func GoRun(handOff time.Duration, fn func(ctx context.Context) error, errHandler func(err error) error) (func(), bool)

GoRun will attempt to run 'fn' in a new goroutine, blocking on time 'handOff' to give time for function return (or panic) and afterwhich considering the function handed off and long-running. If an error is returned at any point, it it will be passed to the provided errHandler function. This can be used to ensure that within 'handOff' that a long running goroutine has successfully started, e.g. during daemon startup. Returns either a cancel function for the provided function's context and 'true', or nil and 'false' indicating function returned error during 'handOff'.

func RetryGoRun

func RetryGoRun(retries int, handOff time.Duration, fn func(ctx context.Context) error, errHandler func(err error) error) (func(), bool)

RetryGoRun will attempt GoRun 'retries' no. times until it returns true, passing <= 0 to retry indefinitely. Returns either a cancel function for the provided function's context (and retry loop) and 'true', or nil and 'false' indicating function returned error during 'handOff' too many times.

func Run

func Run(fn func() error) (err error)

Run will execute the supplied 'fn' catching any panics. Returns either function-returned error or formatted panic.

Types

type FuncRunner

type FuncRunner struct {
	// HandOff is the time after which a blocking function will be considered handed off
	HandOff time.Duration

	// ErrorHandler is the function that errors are passed to when encountered by the
	// provided function. This can be used both for logging, and for error filtering
	ErrorHandler func(err error) error
	// contains filtered or unexported fields
}

FuncRunner provides a means of managing long-running functions e.g. main logic loops.

func (*FuncRunner) Err

func (r *FuncRunner) Err() error

Err returns the last-set error value.

func (*FuncRunner) Go

func (r *FuncRunner) Go(fn func(ctx context.Context) error) bool

Go will attempt to run 'fn' asynchronously. The provided context is used to propagate requested cancel if FuncRunner.Stop() is called. Any returned error will be passed to FuncRunner.ErrorHandler for filtering/logging/etc. Any blocking functions will be waited on for FuncRunner.HandOff amount of time before considering the function as handed off. Returned bool is success state, i.e. returns true if function is successfully handed off or returns within hand off time with nil error.

func (*FuncRunner) Stop

func (r *FuncRunner) Stop() bool

Stop will cancel the context supplied to the running function.

type Service

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

Service provides a simplified means of tracking/running a service, preventing multiple calls to `.Run()` and multiple calls to `.Stop()` when changes of state are in progress.

func (*Service) Done

func (svc *Service) Done() <-chan struct{}

Done returns a channel that's closed when the Manager stops, which is whenever the function supplied in Manager.Start() returns.

func (*Service) Run

func (svc *Service) Run(fn func(context.Context)) bool

Run will run the supplied function until completion, use supplied context to indicate if stopped. Immediately returns false if the service is already running, and true after completd run. You MUST NOT call other Service methods WITHIN provided function.

func (*Service) Running

func (svc *Service) Running() bool

Running will return true if the manager is started.

func (*Service) Stop

func (svc *Service) Stop(fn func()) bool

Stop will attempt to stop the service, and allows you to run supplied function during the mutex locked state change (if was running). Immediately returns false if not running, and true after Service has full stopped. You MUST NOT call other Service methods WITHIN provided function.

func (*Service) Stopping

func (svc *Service) Stopping() bool

Stopping will return true if the manager is in the act of stopping (stop been called, start not yet returned).