workerpool

Documentation

Index

• type AsyncPool
  • func NewDefaultAsyncPool(numWorkers int) AsyncPool
• type EventHandle
• type Hashable
• type Hasher
• type WorkerPool
  • func NewDefaultWorkerPool(numWorkers int) WorkerPool

Types

type AsyncPool

type AsyncPool interface {
	// Go mimics the semantics of the "go" keyword, with the only difference being the `ctx` parameter,
	// which is used to cancel **the submission of task**.
	// **All** tasks successfully submitted will be run eventually, as long as Run are called infinitely many times.
	// Go might block when the AsyncPool is not running.
	Go(ctx context.Context, f func()) error

	// Run runs the AsyncPool.
	Run(ctx context.Context) error
}

AsyncPool provides a simple Goroutine pool, where the order in which jobs are run is non-deterministic.

func NewDefaultAsyncPool

func NewDefaultAsyncPool(numWorkers int) AsyncPool

NewDefaultAsyncPool creates a new AsyncPool that uses the default implementation

type EventHandle

type EventHandle interface {
	// AddEvent adds an `event` object to the internal queue, so that the `f` used to register the handle can be called.
	// Note: events are always processed in the order they are added.
	// Unregistering the EventHandle MAY CAUSE EVENT LOSSES. But for an event lost, any event after it is guaranteed to be lost too.
	// Cancelling `ctx` here will cancel the on-going or next execution of the event.
	AddEvent(ctx context.Context, event interface{}) error

	// SetTimer is used to provide a function that is periodic called, as long as the EventHandle has not been unregistered.
	// The current implementation uses as the base clock source a ticker whose interval is the const workerPoolDefaultClockSourceInterval.
	// DO NOT set an interval less than workerPoolDefaultClockSourceInterval.
	// Cancelling `ctx` here will cancel the on-going or next execution of `f`.
	SetTimer(ctx context.Context, interval time.Duration, f func(ctx context.Context) error) EventHandle

	// Unregister removes the EventHandle from the WorkerPool.
	// Note: Unregister WILL block until the operation has taken effect, i.e. the handler will not be executed after
	// Unregister returns. Unregister WILL NOT attempt to wait for pending events to complete, which means the last few events can be lost.
	Unregister()

	// ErrCh returns a channel that outputs the first non-nil result of events submitted to this EventHandle.
	// Note that a non-nil result of an event cancels the EventHandle, so there is at most one error.
	ErrCh() <-chan error

	// OnExit is used to provide a function that will be called when the handle exits abnormally.
	OnExit(f func(err error)) EventHandle
}

EventHandle is a handle for a registered event. Since events are executed asynchronously, errors should be collected from ErrCh(). EventHandles SHOULD NOT be assumed to be thread safe.

type Hashable

type Hashable interface {
	HashCode() int64
}

Hashable is an object that can be hashed.

type Hasher

type Hasher interface {
	Hash(object Hashable) int64
}

Hasher is actually a "placement driver" that balances the workload. Non-trivial Hashers will be useful if and when we implement dynamic resizing of WorkerPool.

type WorkerPool

type WorkerPool interface {
	// RegisterEvent returns a handle that can be used to trigger the execution of `f`.
	// `f` will be called with a context that is a child of the context with which Run is called.
	// TODO more reasonable usage of contexts, potentially involving context merging.
	RegisterEvent(f func(ctx context.Context, event interface{}) error) EventHandle

	// Run runs the WorkerPool.
	// Internally several Goroutines are spawned.
	Run(ctx context.Context) error
}

WorkerPool runs a number of Goroutines that process the submitted events. Each EventHandle is bound to a fixed worker thread to prevent data races.

func NewDefaultWorkerPool

func NewDefaultWorkerPool(numWorkers int) WorkerPool

NewDefaultWorkerPool creates a new WorkerPool that uses the default implementation