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]) 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. 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.
A new ContextPool should be created with `New().WithContext(ctx)`.
Example ¶
p := New().WithContext(context.Background())
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) Go ¶
func (g *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() and the context passed to other tasks will be canceled.
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) 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 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 runtime.GOMAXPROCS(0). 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().
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) 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 be canceled on 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 runtime.GOMAXPROCS(0). 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.
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) 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 be canceled on 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 runtime.GOMAXPROCS(0). 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.
func (*ResultContextPool[T]) Go ¶
func (p *ResultContextPool[T]) Go(f func(context.Context) (T, error))
Go submits a task to the pool
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]) 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 runtime.GOMAXPROCS(0). 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.
func (*ResultErrorPool[T]) Go ¶
func (p *ResultErrorPool[T]) Go(f func() (T, error))
Go submits a task to the pool
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 be canceled on 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 runtime.GOMAXPROCS(0). 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.
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 ContextPool for tasks that should be canceled on 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 runtime.GOMAXPROCS(0). Panics if n < 1.
Source Files