executor

Documentation

Overview

Package executor is inspired by Java Executor and ThreadPoolExecutor, especially its RejectedExecutionHandler.

Index

• Variables
• func WithCapacity(capacity int) func(*Options)
• type Executor
  • func New(policy FullBufferPolicy, poolSize int, optFns ...func(*Options)) (ex Executor)
  • func NewCallerBlocksOnFullExecutor(n int) Executor
  • func NewCallerRunsOnFullExecutor(n int) Executor
• type FullBufferPolicy
• type Options

Variables

var ErrClosed = errors.New("executor already closed")

ErrClosed is returned by Executor.Execute if Executor.Close has already been called.

Functions

func WithCapacity

func WithCapacity(capacity int) func(*Options)

WithCapacity changes the capacity of the executor's task buffer.

With a capacity that is higher than the number of goroutines, Executor.Execute would take longer to start kicking in its full-buffer policy (either CallerRunsOnFullPolicy or CallerBlocksOnFullPolicy). Useful if you have a list of tasks that is larger than the number of CPUs.

Panics if capacity < 0.

Types

type Executor

type Executor interface {
	// Execute executes the given command.
	//
	// The return error comes from the executor's attempt to run the function, not from the function itself. If the
	// function panics, the poller can recover and continue polling unless the executor has been closed.
	Execute(func()) error

	// Close signals the goroutines in this executor to stop.
	Close() error

	// Wait waits for all goroutines to terminate.
	//
	// A common usage pattern is to Close then Wait to make sure all goroutines have a chance to finish its work
	// and terminate gracefully.
	Wait()
}

Executor is inspired by Java Executor that abstracts submitting a task and executing it.

func New

func New(policy FullBufferPolicy, poolSize int, optFns ...func(*Options)) (ex Executor)

New creates a new Executor with the given full-buffer policy and pool size.

Passing poolSize == 0 effectively returns an executor that executes the function on the same goroutine as caller. Panics if poolSize < 0.

By default, the input buffer capacity is the same as the pool size. Use WithCapacity to change this.

func NewCallerBlocksOnFullExecutor

func NewCallerBlocksOnFullExecutor(n int) Executor

NewCallerBlocksOnFullExecutor returns a new executor that will block if there is no immediately available goroutine to pick up the work.

Passing n == 0 effectively returns an executor that executes the function on the same goroutine as caller. Panics if n < 0.

If you want to be able to queue more task then there are available goroutines, use New with WithCapacity.

func NewCallerRunsOnFullExecutor

func NewCallerRunsOnFullExecutor(n int) Executor

NewCallerRunsOnFullExecutor returns a new executor that will execute the command on same goroutine as caller if a new pool of n goroutines is full.

Passing n == 0 effectively returns an executor that executes the function on the same goroutine as caller. Panics if n < 0.

If you want to be able to queue more task then there are available goroutines, use New with WithCapacity.

type FullBufferPolicy

type FullBufferPolicy int

FullBufferPolicy controls the behaviour of the Executor when its task buffer is full.

This is the equivalent of RejectedExecutionHandler for Java's ThreadPoolExecutor.

const (
	// CallerBlocksOnFullPolicy will cause Executor.Execute to block if the task buffer is full.
	//
	// This is the default behaviour.
	CallerBlocksOnFullPolicy FullBufferPolicy = iota
	// CallerRunsOnFullPolicy will execute the task in the same goroutine that calls Executor.Execute.
	//
	// This is the equivalent of Java's [CallerRunsPolicy].
	//
	// [CallerRunsPolicy]: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/concurrent/ThreadPoolExecutor.CallerRunsPolicy.html
	CallerRunsOnFullPolicy
)

type Options

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

Options allows customisations of the executor returned by New.