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 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() bool
• type WorkerFunc
• type WorkerPool
  • func NewWorkerPool(workers int, queue int) WorkerPool
  • func (pool *WorkerPool) Enqueue(fn WorkerFunc)
  • func (pool *WorkerPool) EnqueueNoBlock(fn WorkerFunc) bool
  • func (pool *WorkerPool) Queue() int
  • func (pool *WorkerPool) Running() bool
  • func (pool *WorkerPool) Start() bool
  • func (pool *WorkerPool) Stop() bool
  • func (pool *WorkerPool) Workers() int

Functions

func ContextWithCancel

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

ContextWithCancel returns a new context.Context impl with cancel.

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 means of tracking a single long-running service, provided protected state changes and preventing multiple instances running. Also providing service state information.

func (*Service) Done

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

Done returns a channel that's closed when Service.Stop() is called. It is the same channel provided to the currently running service function.

func (*Service) Run

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

Run will run the supplied function until completion, use given context to propagate cancel. Immediately returns false if the Service is already running, and true after completed run.

func (*Service) Running

func (svc *Service) Running() bool

Running returns if Service is running (i.e. state NOT stopped / stopping).

func (*Service) Stop

func (svc *Service) Stop() bool

Stop will attempt to stop the service, cancelling the running function's context. Immediately returns false if not running, and true only after Service is fully stopped.

type WorkerFunc

type WorkerFunc func(context.Context)

WorkerFunc represents a function processable by a worker in WorkerPool. Note that implementations absolutely MUST check whether passed context is Done() otherwise stopping the pool may block for large periods of time.

type WorkerPool

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

WorkerPool provides a means of enqueuing asynchronous work.

func NewWorkerPool

func NewWorkerPool(workers int, queue int) WorkerPool

NewWorkerPool returns a new WorkerPool with provided worker count and WorkerFunc queue size. The number of workers represents how many WorkerFuncs can be executed simultaneously, and the queue size represents the max number of WorkerFuncs that can be queued at any one time.

func (*WorkerPool) Enqueue

func (pool *WorkerPool) Enqueue(fn WorkerFunc)

Enqueue will add provided WorkerFunc to the queue to be performed when there is a free worker. This will block until the function has been queued. 'fn' will ALWAYS be executed, even on pool close, which can be determined via context <-ctx.Done(). WorkerFuncs MUST respect the passed context.

func (*WorkerPool) EnqueueNoBlock

func (pool *WorkerPool) EnqueueNoBlock(fn WorkerFunc) bool

EnqueueNoBlock attempts Enqueue but returns false if not executed.

func (*WorkerPool) Queue

func (pool *WorkerPool) Queue() int

Queue returns the number of currently queued WorkerFuncs.

func (*WorkerPool) Running

func (pool *WorkerPool) Running() bool

Running returns whether the worker pool is running.

func (*WorkerPool) Start

func (pool *WorkerPool) Start() bool

Start will attempt to start the worker pool, asynchronously. Return is success state.

func (*WorkerPool) Stop

func (pool *WorkerPool) Stop() bool

Stop will attempt to stop the worker pool, this will block until stopped. Return is success state.

func (*WorkerPool) Workers

func (pool *WorkerPool) Workers() int

Workers returns the number of currently active workers.