run: h12.io/run Index | Files

package run

import "h12.io/run"

Package run provides graceful goroutine orchestration.

Index

Package Files

closer.go group.go log.go pool.go run.go

Variables

var ErrClosed = errors.New("run.Closer: already closed")

ErrClosed is returned when the Closer is already closed

var ErrDispatchTimeout = errors.New("failed to dispatch the goroutine due to timeout")

ErrDispatchTimeout is returned when the context is cancelled when waiting for a task to be dispatched

func Closer Uses

func Closer(runner Runner) io.Closer

Closer wraps a Runner into a Closer, whose Close method will cancel the runner and wait for its exit and return its error

func WaitCloser Uses

func WaitCloser(runner Runner) io.Closer

WaitCloser wraps a Runner into a Closer, whose Close method will wait for the runner to exit and return its error

type Event Uses

type Event int

Event enum of a runner

const (
    Start Event = iota // runner starts
    Exit               // runner exits
)

Event constants

func (Event) String Uses

func (e Event) String() string

String representation of int enum

type Func Uses

type Func func(context.Context) error

The Func type is an adapter to allow the use of ordinary functions as runners. If f is a function with the appropriate signature, Func(f) is a Runner that calls f.

func (Func) Run Uses

func (f Func) Run(ctx context.Context) error

Run calls f(ctx)

type GoroutinePool Uses

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

GoroutinePool provides a goroutine pool, see the documentation for method Go for more information

func NewGoroutinePool Uses

func NewGoroutinePool(options ...PoolOption) *GoroutinePool

NewGoroutinePool creates a new GoroutinePool based on the options provided

func (*GoroutinePool) Close Uses

func (p *GoroutinePool) Close() error

Close stops the pool from accepting new tasks, waits for existing tasks complete and return nil. All subsequent calls will return ErrClosed

func (*GoroutinePool) Go Uses

func (p *GoroutinePool) Go(ctx context.Context, fn func()) error

Go tries to dispatch function fn onto its own goroutine. It returns nil if fn is successfully dispatched. It returns ErrClosed if the pool is already closed. It returns ErrDispatchTimeout if the context is cancelled when waiting for an idle goroutine to be available.

A gouroutine will stay idle and be reused for a period specified by IdleTime option (default 1s).

If Max option is specified, there will be a maximum limit on the goroutines that the pool can hold in total, and Go will block and wait for an idle goroutine is available. Otherwise, there is no limit on the goroutine number.

type Group Uses

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

Group combines multiple concurrent tasks into one

func NewGroup Uses

func NewGroup(ctx context.Context, options ...GroupOption) *Group

NewGroup creates a new Group

func (*Group) Go Uses

func (g *Group) Go(runner Runner) error

Go runs the given runner in the internal goroutine pool. It returns nil when the goroutine is dispatched succesfully. It returns ErrDispatchTimeout if the context of the group is cancelled when waiting for an idle goroutine to be available. The first error return from a runner cancels the group, and all subsequent calls to Go as well as Wait will return the error

func (*Group) Wait Uses

func (g *Group) Wait() error

Wait waits for all goroutines exit and returns the first returned error

type GroupOption Uses

type GroupOption func(*Group)

GroupOption is used to specify an option for Group

func Log Uses

func Log(logFunc func(info *LogInfo)) GroupOption

Log specifies the logging function for a group, if not set, the LogInfo is not generated

func Pool Uses

func Pool(p *GoroutinePool) GroupOption

Pool specifies the goroutine pool for a group, if not set, a dummy implementation is used (always starting new goroutines)

func Recover Uses

func Recover(yes bool) GroupOption

Recover specifies if a panic in the runner goroutine should be recovered or not, if not set, the default behavior is recovered.

type GroupPool Uses

type GroupPool interface {
    Go(ctx context.Context, fn func()) error
}

GroupPool is an interface for a goroutine pool used by Group

type LogInfo Uses

type LogInfo struct {
    Runner Runner
    Event  Event
    Err    error
}

LogInfo is a logging event of a runner

func (*LogInfo) RunnerName Uses

func (li *LogInfo) RunnerName() string

RunnerName returns a meaningful name of the runner for logging

func (*LogInfo) String Uses

func (li *LogInfo) String() string

LogInfo provides a default string representation of the LogInfo

type PanicError Uses

type PanicError struct {
    Err   interface{}
    Stack []byte
}

PanicError represents recovered panic info

func (*PanicError) Error Uses

func (e *PanicError) Error() string

Error satisifies error interface

type PoolOption Uses

type PoolOption func(*GoroutinePool)

PoolOption is used to specify an option for GoroutinePool

func IdleTime Uses

func IdleTime(idleTime time.Duration) PoolOption

IdleTime returns the option to specify the idle time before a goroutine exits and releases the resource if no task is submitted, if not specified, the default idle time is 1s

func Max Uses

func Max(n int) PoolOption

Max returns the option to specifiy the maximum number of goroutines that a GoroutinePool can hold, if not specified, there is no upper limit

type Runner Uses

type Runner interface {
    Run(context.Context) error
}

Runner defines the Run method to be exeucuted within a goroutine

Package run imports 8 packages (graph). Updated 2018-12-16. Refresh now. Tools for package owners.