goproc

README

goproc

goproc is a golang module containing components for goroutine and timer control.

Basic Components

Controller

A simple controller of background goroutines, which can cancel or wait for all under control goroutines to return.

TimeoutChan

A type representing a channel for Deadliner objects. TimeoutChan accepts Deadliner from TimeoutChan.In and sends Deadliner to Timeout.Out when its deadline is reached.

The underlying implementation of TimeoutChan timer scheduling is similar to the internal golang timer but with a higher level abstraction and better-controlled behavior.

Features:

• Channel-like behavior with limited/unlimited buffer
• Deadliner management and timeout scheduling
• Guaranteed out-order of deadliners in TimeoutChan buffer
  • While working with limited TimeoutChan, the order is only guaranteed in the limited buffer range

See example test cases for details.

Documentation

Index

• type Controller
  • func NewController(ctx context.Context, name string) *Controller
  • func (c *Controller) Die() bool
  • func (c *Controller) Go(g Goroutine) *Controller
  • func (c *Controller) GoWithRecover(g Goroutine, rf Recover) *Controller
  • func (c *Controller) Shutdown()
  • func (c *Controller) Wait()
  • func (c *Controller) WithDeadline(deadline time.Time) *Controller
  • func (c *Controller) WithTimeout(timeout time.Duration) *Controller
  • func (c *Controller) WithValue(key interface{}, value interface{}) *Controller
• type Deadliner
• type Goroutine
• type Prioritier
• type PriorityQueue
  • func NewPriorityQueue(desc bool, size int) *PriorityQueue
  • func (q *PriorityQueue) Clear() int
  • func (q PriorityQueue) Len() int
  • func (q PriorityQueue) Less(i, j int) bool
  • func (q *PriorityQueue) Peek() interface{}
  • func (q *PriorityQueue) Pop() interface{}
  • func (q *PriorityQueue) Push(x interface{})
  • func (q PriorityQueue) Swap(i, j int)
• type Recover
• type TimeoutChan
  • func NewTimeoutChan(ctx context.Context, resolution time.Duration, limit int) *TimeoutChan
  • func (c *TimeoutChan) Clear() int
  • func (c *TimeoutChan) Close()
  • func (c *TimeoutChan) Push(in Deadliner)
  • func (c *TimeoutChan) Shutdown()
  • func (c *TimeoutChan) Stats() TimeoutChanStats
• type TimeoutChanStats
  • func (s TimeoutChanStats) String() string

Types

type Controller

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

Controller implements a simple controller of goroutines, which can cancel or wait for all under control goroutines to return.

func NewController

func NewController(ctx context.Context, name string) *Controller

NewController creates a new goproc Controller.

func (*Controller) Die

func (c *Controller) Die() bool

Die tells whether c is already cancelled - it always returns true after the first time c.Shutdown() or c.Wait() is called.

func (*Controller) Go

func (c *Controller) Go(g Goroutine) *Controller

Go initiates a new goroutine for g and gains control on the goroutine through a context.Context argument.

func (*Controller) GoWithRecover

func (c *Controller) GoWithRecover(g Goroutine, rf Recover) *Controller

GoWithRecover initiates a new goroutine for g and gains control on the goroutine through a context.Context argument. Any panic from g will be captured and handled by rf.

func (*Controller) Shutdown

func (c *Controller) Shutdown()

Shutdown cancels and waits for any goroutine under control.

func (*Controller) Wait

func (c *Controller) Wait()

Wait waits for any goroutine under control to exit.

func (*Controller) WithDeadline

func (c *Controller) WithDeadline(deadline time.Time) *Controller

WithDeadline returns a copy of c with deadline set to internal context object, which will be passed to the Goroutine functions in subsequent c.Go* calls.

Note that unlike a child context, the returned object still holds the control of c, which means cancelling the returned Controller would actually cancel all goroutines started by c.

func (*Controller) WithTimeout

func (c *Controller) WithTimeout(timeout time.Duration) *Controller

WithTimeout returns a copy of c with timeout set to internal context object, which will be passed to the Goroutine functions in subsequent c.Go* calls.

Note that unlike a child context, the returned object still holds the control of c, which means cancelling the returned Controller would actually cancel all goroutines started by c.

func (*Controller) WithValue

func (c *Controller) WithValue(key interface{}, value interface{}) *Controller

WithValue returns a copy of c with key->value added to internal context object, which will be passed to the Goroutine functions in subsequent c.Go* calls. For good practice of context key-value usage, reference context package docs.

Note that unlike a child context, the returned object still holds the control of c, which means cancelling the returned Controller would actually cancel all goroutines started by c.

type Deadliner

type Deadliner interface {
	Deadline() time.Time
}

Deadliner is the interface implemented by an object that can return a deadline time.

type Goroutine

type Goroutine func(ctx context.Context)

Goroutine defines the function type for Controller.

type Prioritier

type Prioritier interface {
	Priority() int64
}

Prioritier is the interface implemented by an object that can return a int64 priority.

type PriorityQueue

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

PriorityQueue is heap-implementation of priority queue.

func NewPriorityQueue

func NewPriorityQueue(desc bool, size int) *PriorityQueue

NewPriorityQueue creates a new PriorityQueue.

func (*PriorityQueue) Clear

func (q *PriorityQueue) Clear() int

Clear clears priority queue.

func (PriorityQueue) Len

func (q PriorityQueue) Len() int

Len implements Len method of sort.Interface.

func (PriorityQueue) Less

func (q PriorityQueue) Less(i, j int) bool

Less implements Less method of sort.Interface.

func (*PriorityQueue) Peek

func (q *PriorityQueue) Peek() interface{}

Peek returns the top element of the priority queue. User should ensure the queue is not empty before calling Peek.

func (*PriorityQueue) Pop

func (q *PriorityQueue) Pop() interface{}

Pop implements Pop method of heap.Interface.

func (*PriorityQueue) Push

func (q *PriorityQueue) Push(x interface{})

Push implements Push method of heap.Interface.

func (PriorityQueue) Swap

func (q PriorityQueue) Swap(i, j int)

Swap implements Swap method of sort.Interface.

type Recover

type Recover func(r interface{})

Recover defines the recover handler function type for Controller.

type TimeoutChan

type TimeoutChan struct {
	In  chan<- Deadliner
	Out <-chan Deadliner
	// contains filtered or unexported fields
}

TimeoutChan is a type representing a channel for Deadliner objects. TimeoutChan accepts Deadliner from TimeoutChan.In and sends Deadliner to Timeout.Out when its deadline is reached.

func NewTimeoutChan

func NewTimeoutChan(ctx context.Context, resolution time.Duration, limit int) *TimeoutChan

NewTimeoutChan creates a new TimeoutChan. With 0 limit an unlimited timeout chan will be returned.

func (*TimeoutChan) Clear

func (c *TimeoutChan) Clear() int

Clear clears buffered Deadliners in TimeoutChan.

func (*TimeoutChan) Close

func (c *TimeoutChan) Close()

Close closes TimeoutChan and waits until all buffered Deadliners in TimeoutChan to be sent and read in TimeoutChan.Out before it returns.

func (*TimeoutChan) Push

func (c *TimeoutChan) Push(in Deadliner)

Push is an alias of TimeoutChan.In <- (in Deadliner), but bypasses background push process for unlimited TimeoutChan.

func (*TimeoutChan) Shutdown

func (c *TimeoutChan) Shutdown()

Shutdown closes TimeoutChan and returns immediately, any buffered Deadliners in TimeoutChan will be ignored.

func (*TimeoutChan) Stats

func (c *TimeoutChan) Stats() TimeoutChanStats

Stats returns TimeoutChan statistics.

type TimeoutChanStats

type TimeoutChanStats struct {
	Pushed  int
	Popped  int
	Cleared int
}

TimeoutChanStats contains timeout chan statistics returned from TimeoutChan.Stats().

func (TimeoutChanStats) String

func (s TimeoutChanStats) String() string

String implements fmt.Stringer.