Workerpool v2 API

[kaworu]

This issue lists all breaking changes that are being considered for an eventual v2 release. The discussion started in this PR.

Breaking changes

Context-aware blocking operations

Add context.Context parameter to all blocking methods:

• Submit(ctx context.Context, id string, f func(ctx context.Context) error) error
• Drain(ctx context.Context) ([]Task, error)
• Close(ctx context.Context) error

Current design ties the entire lifecycle to a single context at construction time and doesn't handle per-operation cancellation vs per-task cancellation separately.

"context should be passed to blocking functions that should be something you can cancel. That would be Submit, Drain, Close, etc." — chancez, PR #44

---

Constructor doesn't start goroutines

Remove automatic goroutine spawning in New() and NewWithContext(). Add explicit Run(ctx context.Context) error method.

// v1
wp := workerpool.New(10)
wp.Submit("task1", taskFunc)

// v2
wp := workerpool.New(10)
go wp.Run(context.Background())
wp.Submit(ctx, "task1", taskFunc)

"we start a goroutine in our constructor, which IMO, is an anti-pattern anyways and we shouldn't start any Goroutines, and should instead expect the caller to do it." — chancez, PR #44

---

Restartable worker pools

Allow calling Run() again after Close() to restart the pool. v1 pools are permanently closed.

---

Option validation returns errors

Make New() and NewWithContext() return (*WorkerPool, error) instead of *WorkerPool.

// v1
wp := workerpool.New(10, opts...) // panics on invalid options

// v2
wp, err := workerpool.New(10, opts...)

// TODO(v2): New/NewWithContext should return an error so that option
// validation can propagate errors instead of panicking.

---

Type-safe callback/drain separation

When WithResultCallback is used, don't expose Drain() method (possibly via interface or separate types).

// TODO(v2): remove ErrCallbackSet — a pool configured with
// WithResultCallback should not expose Drain.

Possible approaches: return different interfaces based on options, or separate types (WorkerPool vs WorkerPoolWithCallback).

---

Related v1 Improvements

• PR Add WithResultCallback option to avoid unbounded result accumulation #114: Added WithResultCallback to avoid unbounded result accumulation
• PR workerpool: reject Submit when parent context is done #111: Submit rejects when parent context is done
• PR add NewWithContext #44: Added NewWithContext for context cancellation

Design Principles

• Blocking APIs take a context for cancellation/timeout
• Constructors don't start goroutines
• Library code returns errors, not panics
• Type safety over runtime checks

References

• Issue #45
• PR #44 discussion
• Rewrite prototype