README
¶
go-worker-pool
Bounded goroutine pool with backpressure and futures for Go
Installation
go get github.com/philiprehberger/go-worker-pool
Usage
Basic Pool
import "github.com/philiprehberger/go-worker-pool"
p := workerpool.New(4) // max 4 concurrent goroutines
for i := 0; i < 100; i++ {
p.Submit(func() {
// do work
})
}
p.Wait() // block until all tasks complete
Future
f := workerpool.Go(p, func() (int, error) {
return computeExpensiveValue(), nil
})
// do other work...
val, err := f.Get() // block until result is ready
Context-Aware Submit
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
err := p.SubmitCtx(ctx, func() {
// do work
})
if err != nil {
// context was cancelled while waiting for a worker slot
}
API
| Function / Type | Description |
|---|---|
New(concurrency int) *Pool |
Create a new pool with the given concurrency limit |
(*Pool) Submit(fn func()) |
Submit work; blocks if all workers are busy |
(*Pool) SubmitCtx(ctx, fn) error |
Submit with context; returns ctx.Err() if cancelled while waiting |
(*Pool) Wait() |
Block until all submitted work completes |
(*Pool) Stop() |
Mark stopped and wait; further submits panic |
(*Pool) Running() int |
Approximate number of active goroutines |
Go[T](p, fn) *Future[T] |
Submit work that returns a value; returns a Future |
(*Future[T]) Get() (T, error) |
Block until result is ready |
(*Future[T]) Done() bool |
Non-blocking check if complete |
Development
go test ./...
go vet ./...
License
MIT
Documentation
¶
Overview ¶
Package workerpool provides a bounded goroutine pool for Go.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Future ¶
type Future[T any] struct { // contains filtered or unexported fields }
Future represents a value that will be available at some point in the future. It is safe to call Get and Done from multiple goroutines concurrently.
func Go ¶
Go submits a function that returns a value and an error to the pool, and returns a Future that can be used to retrieve the result. The function runs asynchronously in the pool. Use Get to block until the result is ready.
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
Pool is a bounded goroutine pool that limits the number of concurrently running goroutines. It uses a buffered channel as a semaphore to enforce backpressure — when all worker slots are occupied, Submit blocks until a slot becomes available.
func New ¶
New creates a new Pool with the given concurrency limit. The concurrency parameter controls how many goroutines can run simultaneously. It panics if concurrency is less than 1.
func (*Pool) Running ¶
Running returns the approximate number of goroutines currently executing work. Because goroutines start and finish concurrently, the value is an approximation.
func (*Pool) Stop ¶
func (p *Pool) Stop()
Stop marks the pool as stopped and waits for all in-flight work to complete. After Stop returns, any call to Submit or SubmitCtx will panic.
func (*Pool) Submit ¶
func (p *Pool) Submit(fn func())
Submit sends a function to the pool for execution. It blocks if all worker slots are currently occupied (backpressure). The function runs in its own goroutine once a slot is available. Submit panics if the pool has been stopped.
func (*Pool) SubmitCtx ¶
SubmitCtx sends a function to the pool for execution with context support. It returns ctx.Err() if the context is cancelled or times out while waiting for a worker slot. If a slot is acquired, the function runs in its own goroutine and nil is returned. SubmitCtx panics if the pool has been stopped.
Source Files