Documentation
¶
Overview ¶
Package parmap provides a bounded parallel map over a slice of inputs.
It is a thin wrapper around golang.org/x/sync/errgroup that adds two things our callers want and errgroup doesn't:
- Per-item results: callers get a slice of Result in input order. The worker function encodes per-item errors inside its returned value (e.g., as a status field). errgroup's first-error aggregation isn't a good fit when every item must report its own outcome (render status, update result, etc.).
- A "didn't start" signal: items that were never invoked because ctx was already done are flagged via Result.Cancelled, so callers can distinguish "cancelled before start" from "started but bailed out inside worker".
Concurrency is bounded via errgroup.Group.SetLimit — the worker goroutine for each item only launches when a slot is free, so peak goroutine count stays ≤ limit even with millions of items.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Result ¶
Result wraps the output of a single Map invocation for one input item.
Cancelled is true when ctx was done before the worker function was invoked, so Value is the zero value of Out. Workers that did run and observed cancellation inside their body are responsible for surfacing that in their returned Value (so callers can distinguish "didn't start" from "started but bailed out").
func Map ¶
func Map[In, Out any]( ctx context.Context, limit int, items []In, onProgress func(completed, total int), worker func(context.Context, In) Out, ) []Result[Out]
Map runs worker for each item in items with at most limit concurrent goroutines, respecting ctx cancellation. Results are returned in input order.
Behaviour:
- Returns nil for an empty items slice.
- limit < 1 is treated as 1.
- onProgress, when non-nil, is invoked once per completed item (success or cancelled). Invocations are serialized under an internal mutex and observe a monotonically increasing 'completed' value, so callers do not need to add their own synchronization. The callback is invoked synchronously from worker goroutines: keep it fast, since a slow callback backpressures the entire worker pool.
- Items that never start because ctx is done set Result.Cancelled = true and never call worker. Items that did start always call worker with ctx; it is the worker function's job to react to ctx cancellation (e.g., by returning early).
- Internally uses errgroup.Group.SetLimit: worker goroutines are launched lazily, so peak goroutine count is bounded by limit regardless of items length.
- Panics inside worker are NOT recovered — they propagate through errgroup and crash the program. This matches errgroup.Group.Go's contract; recover inside worker if you need different behaviour.
Source Files