Documentation
¶
Index ¶
- type ContextPool
- type ErrorPool
- type Pool
- type ResultContextPool
- func (p *ResultContextPool[T]) Go(f func(context.Context) (T, error))
- func (p *ResultContextPool[T]) Wait() ([]T, error)
- func (p *ResultContextPool[T]) WithCancelOnError() *ResultContextPool[T]
- func (p *ResultContextPool[T]) WithCollectErrored() *ResultContextPool[T]
- func (p *ResultContextPool[T]) WithFirstError() *ResultContextPool[T]
- func (p *ResultContextPool[T]) WithMaxGoroutines(n int) *ResultContextPool[T]
- type ResultErrorPool
- func (p *ResultErrorPool[T]) Go(f func() (T, error))
- func (p *ResultErrorPool[T]) Wait() ([]T, error)
- func (p *ResultErrorPool[T]) WithCollectErrored() *ResultErrorPool[T]
- func (p *ResultErrorPool[T]) WithContext(ctx context.Context) *ResultContextPool[T]
- func (p *ResultErrorPool[T]) WithFirstError() *ResultErrorPool[T]
- func (p *ResultErrorPool[T]) WithMaxGoroutines(n int) *ResultErrorPool[T]
- type ResultPool
- func (p *ResultPool[T]) Go(f func() T)
- func (p *ResultPool[T]) MaxGoroutines() int
- func (p *ResultPool[T]) Wait() []T
- func (p *ResultPool[T]) WithContext(ctx context.Context) *ResultContextPool[T]
- func (p *ResultPool[T]) WithErrors() *ResultErrorPool[T]
- func (p *ResultPool[T]) WithMaxGoroutines(n int) *ResultPool[T]
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ContextPool ¶
type ContextPool struct {
// contains filtered or unexported fields
}
ContextPool is a pool that runs tasks that take a context. A new ContextPool should be created with `New().WithContext(ctx)`.
The configuration methods (With*) will panic if they are used after calling Go() for the first time.
func (*ContextPool) Go ¶
func (p *ContextPool) Go(f func(ctx context.Context) error)
Go submits a task. If it returns an error, the error will be collected and returned by Wait(). If all goroutines in the pool are busy, a call to Go() will block until the task can be started.
func (*ContextPool) Wait ¶
func (p *ContextPool) Wait() error
Wait cleans up all spawned goroutines, propagates any panics, and returns an error if any of the tasks errored.
func (*ContextPool) WithCancelOnError ¶ added in v0.2.0
func (p *ContextPool) WithCancelOnError() *ContextPool
WithCancelOnError configures the pool to cancel its context as soon as any task returns an error or panics. By default, the pool's context is not canceled until the parent context is canceled.
In this case, all errors returned from the pool after the first will likely be context.Canceled - you may want to also use (*ContextPool).WithFirstError() to configure the pool to only return the first error.
Example ¶
p := New().
WithMaxGoroutines(4).
WithContext(context.Background()).
WithCancelOnError()
for i := 0; i < 3; i++ {
i := i
p.Go(func(ctx context.Context) error {
if i == 2 {
return errors.New("I will cancel all other tasks!")
}
<-ctx.Done()
return nil
})
}
err := p.Wait()
fmt.Println(err)
Output: I will cancel all other tasks!
func (*ContextPool) WithFirstError ¶
func (p *ContextPool) WithFirstError() *ContextPool
WithFirstError configures the pool to only return the first error returned by a task. By default, Wait() will return a combined error. This is particularly useful for (*ContextPool).WithCancelOnError(), where all errors after the first are likely to be context.Canceled.
func (*ContextPool) WithMaxGoroutines ¶
func (p *ContextPool) WithMaxGoroutines(n int) *ContextPool
WithMaxGoroutines limits the number of goroutines in a pool. Defaults to unlimited. Panics if n < 1.
type ErrorPool ¶
type ErrorPool struct {
// contains filtered or unexported fields
}
ErrorPool is a pool that runs tasks that may return an error. Errors are collected and returned by Wait().
The configuration methods (With*) will panic if they are used after calling Go() for the first time.
A new ErrorPool should be created using `New().WithErrors()`.
Example ¶
p := New().WithErrors()
for i := 0; i < 3; i++ {
i := i
p.Go(func() error {
if i == 2 {
return errors.New("oh no!")
}
return nil
})
}
err := p.Wait()
fmt.Println(err)
Output: oh no!
func (*ErrorPool) Go ¶
Go submits a task to the pool. If all goroutines in the pool are busy, a call to Go() will block until the task can be started.
func (*ErrorPool) Wait ¶
Wait cleans up any spawned goroutines, propagating any panics and returning any errors from tasks.
func (*ErrorPool) WithContext ¶
func (p *ErrorPool) WithContext(ctx context.Context) *ContextPool
WithContext converts the pool to a ContextPool for tasks that should run under the same context, such that they each respect shared cancellation. For example, WithCancelOnError can be configured on the returned pool to signal that all goroutines should be cancelled upon the first error.
func (*ErrorPool) WithFirstError ¶
WithFirstError configures the pool to only return the first error returned by a task. By default, Wait() will return a combined error.
func (*ErrorPool) WithMaxGoroutines ¶
WithMaxGoroutines limits the number of goroutines in a pool. Defaults to unlimited. Panics if n < 1.
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
Pool is a pool of goroutines used to execute tasks concurrently.
Tasks are submitted with Go(). Once all your tasks have been submitted, you must call Wait() to clean up any spawned goroutines and propagate any panics.
Goroutines are started lazily, so creating a new pool is cheap. There will never be more goroutines spawned than there are tasks submitted.
The configuration methods (With*) will panic if they are used after calling Go() for the first time.
Pool is efficient, but not zero cost. It should not be used for very short tasks. Startup and teardown come with an overhead of around 1µs, and each task has an overhead of around 300ns.
Example ¶
p := New().WithMaxGoroutines(3)
for i := 0; i < 5; i++ {
p.Go(func() {
fmt.Println("conc")
})
}
p.Wait()
Output: conc conc conc conc conc
func (*Pool) Go ¶
func (p *Pool) Go(f func())
Go submits a task to be run in the pool. If all goroutines in the pool are busy, a call to Go() will block until the task can be started.
func (*Pool) MaxGoroutines ¶
MaxGoroutines returns the maximum size of the pool.
func (*Pool) Wait ¶
func (p *Pool) Wait()
Wait cleans up spawned goroutines, propagating any panics that were raised by a tasks.
func (*Pool) WithContext ¶
func (p *Pool) WithContext(ctx context.Context) *ContextPool
WithContext converts the pool to a ContextPool for tasks that should run under the same context, such that they each respect shared cancellation. For example, WithCancelOnError can be configured on the returned pool to signal that all goroutines should be cancelled upon the first error.
func (*Pool) WithErrors ¶
WithErrors converts the pool to an ErrorPool so the submitted tasks can return errors.
func (*Pool) WithMaxGoroutines ¶
WithMaxGoroutines limits the number of goroutines in a pool. Defaults to unlimited. Panics if n < 1.
type ResultContextPool ¶
type ResultContextPool[T any] struct { // contains filtered or unexported fields }
ResultContextPool is a pool that runs tasks that take a context and return a result. The context passed to the task will be canceled if any of the tasks return an error, which makes its functionality different than just capturing a context with the task closure.
The configuration methods (With*) will panic if they are used after calling Go() for the first time.
func (*ResultContextPool[T]) Go ¶
func (p *ResultContextPool[T]) Go(f func(context.Context) (T, error))
Go submits a task to the pool. If all goroutines in the pool are busy, a call to Go() will block until the task can be started.
func (*ResultContextPool[T]) Wait ¶
func (p *ResultContextPool[T]) Wait() ([]T, error)
Wait cleans up all spawned goroutines, propagates any panics, and returns an error if any of the tasks errored.
func (*ResultContextPool[T]) WithCancelOnError ¶ added in v0.2.0
func (p *ResultContextPool[T]) WithCancelOnError() *ResultContextPool[T]
WithCancelOnError configures the pool to cancel its context as soon as any task returns an error. By default, the pool's context is not canceled until the parent context is canceled.
func (*ResultContextPool[T]) WithCollectErrored ¶
func (p *ResultContextPool[T]) WithCollectErrored() *ResultContextPool[T]
WithCollectErrored configures the pool to still collect the result of a task even if the task returned an error. By default, the result of tasks that errored are ignored and only the error is collected.
func (*ResultContextPool[T]) WithFirstError ¶
func (p *ResultContextPool[T]) WithFirstError() *ResultContextPool[T]
WithFirstError configures the pool to only return the first error returned by a task. By default, Wait() will return a combined error.
func (*ResultContextPool[T]) WithMaxGoroutines ¶
func (p *ResultContextPool[T]) WithMaxGoroutines(n int) *ResultContextPool[T]
WithMaxGoroutines limits the number of goroutines in a pool. Defaults to unlimited. Panics if n < 1.
type ResultErrorPool ¶
type ResultErrorPool[T any] struct { // contains filtered or unexported fields }
ResultErrorPool is a pool that executes tasks that return a generic result type and an error. Tasks are executed in the pool with Go(), then the results of the tasks are returned by Wait().
The order of the results is not guaranteed to be the same as the order the tasks were submitted. If your use case requires consistent ordering, consider using the `stream` package or `Map` from the `iter` package.
The configuration methods (With*) will panic if they are used after calling Go() for the first time.
func (*ResultErrorPool[T]) Go ¶
func (p *ResultErrorPool[T]) Go(f func() (T, error))
Go submits a task to the pool. If all goroutines in the pool are busy, a call to Go() will block until the task can be started.
func (*ResultErrorPool[T]) Wait ¶
func (p *ResultErrorPool[T]) Wait() ([]T, error)
Wait cleans up any spawned goroutines, propagating any panics and returning the results and any errors from tasks.
func (*ResultErrorPool[T]) WithCollectErrored ¶
func (p *ResultErrorPool[T]) WithCollectErrored() *ResultErrorPool[T]
WithCollectErrored configures the pool to still collect the result of a task even if the task returned an error. By default, the result of tasks that errored are ignored and only the error is collected.
func (*ResultErrorPool[T]) WithContext ¶
func (p *ResultErrorPool[T]) WithContext(ctx context.Context) *ResultContextPool[T]
WithContext converts the pool to a ResultContextPool for tasks that should run under the same context, such that they each respect shared cancellation. For example, WithCancelOnError can be configured on the returned pool to signal that all goroutines should be cancelled upon the first error.
func (*ResultErrorPool[T]) WithFirstError ¶
func (p *ResultErrorPool[T]) WithFirstError() *ResultErrorPool[T]
WithFirstError configures the pool to only return the first error returned by a task. By default, Wait() will return a combined error.
func (*ResultErrorPool[T]) WithMaxGoroutines ¶
func (p *ResultErrorPool[T]) WithMaxGoroutines(n int) *ResultErrorPool[T]
WithMaxGoroutines limits the number of goroutines in a pool. Defaults to unlimited. Panics if n < 1.
type ResultPool ¶
type ResultPool[T any] struct { // contains filtered or unexported fields }
ResultPool is a pool that executes tasks that return a generic result type. Tasks are executed in the pool with Go(), then the results of the tasks are returned by Wait().
The order of the results is not guaranteed to be the same as the order the tasks were submitted. If your use case requires consistent ordering, consider using the `stream` package or `Map` from the `iter` package.
Example ¶
p := NewWithResults[int]()
for i := 0; i < 10; i++ {
i := i
p.Go(func() int {
return i * 2
})
}
res := p.Wait()
// Result order is nondeterministic, so sort them first
sort.Ints(res)
fmt.Println(res)
Output: [0 2 4 6 8 10 12 14 16 18]
func NewWithResults ¶
func NewWithResults[T any]() *ResultPool[T]
NewWithResults creates a new ResultPool for tasks with a result of type T.
The configuration methods (With*) will panic if they are used after calling Go() for the first time.
func (*ResultPool[T]) Go ¶
func (p *ResultPool[T]) Go(f func() T)
Go submits a task to the pool. If all goroutines in the pool are busy, a call to Go() will block until the task can be started.
func (*ResultPool[T]) MaxGoroutines ¶
func (p *ResultPool[T]) MaxGoroutines() int
MaxGoroutines returns the maximum size of the pool.
func (*ResultPool[T]) Wait ¶
func (p *ResultPool[T]) Wait() []T
Wait cleans up all spawned goroutines, propagating any panics, and returning a slice of results from tasks that did not panic.
func (*ResultPool[T]) WithContext ¶
func (p *ResultPool[T]) WithContext(ctx context.Context) *ResultContextPool[T]
WithContext converts the pool to a ResultContextPool for tasks that should run under the same context, such that they each respect shared cancellation. For example, WithCancelOnError can be configured on the returned pool to signal that all goroutines should be cancelled upon the first error.
func (*ResultPool[T]) WithErrors ¶
func (p *ResultPool[T]) WithErrors() *ResultErrorPool[T]
WithErrors converts the pool to an ResultErrorPool so the submitted tasks can return errors.
func (*ResultPool[T]) WithMaxGoroutines ¶
func (p *ResultPool[T]) WithMaxGoroutines(n int) *ResultPool[T]
WithMaxGoroutines limits the number of goroutines in a pool. Defaults to unlimited. Panics if n < 1.
Source Files