Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

refactor(workflow): bound parallel task admission (#20399)

Sbaaoui Idrissab30f51db9ae
diff --git a/internal/agent/workflowx/parallel.go b/internal/agent/workflowx/parallel.go
index 8b9a5c2dc5..48733e87ef 100644
--- a/internal/agent/workflowx/parallel.go
+++ b/internal/agent/workflowx/parallel.go
@@ -78,8 +78,7 @@ type parallelOptions struct {
//
// n <= 1 — sequential execution on the calling goroutine (no
// goroutines are spawned for any input length).
-// n > 1 — bounded fan-out using a semaphore of size n; the first
-// item still runs on the main goroutine.
+// n > 1 — up to n workers invoke items concurrently.
//
// The default is 0 (sequential).
func WithParallelMaxConcurrency(n int) ParallelOption {
@@ -379,7 +378,7 @@ func runParallelInvoke[I, O any](
bridgeState = newParallelBridgeState(prev.ItemCheckpoints)
}
- // Run all items. The sequential / semaphore-bounded fan-out
+ // Run all items. The sequential / worker-bounded fan-out
// is delegated to runParallelFanout.
results := runParallelFanout(ctx, nodeKey, sub, effectiveItems, indicesToProcess, options, bridgeState)
@@ -623,17 +622,16 @@ type parallelTaskResult struct {
// runParallelFanout executes the per-item sub-workflow calls
// according to the configured concurrency policy and returns a
-// channel of results. The channel is closed once every item has
-// reported (success, interrupt, or error).
+// channel of results. On cancellation it reports one error for
+// unscheduled work, then closes after admitted items finish.
//
// Concurrency policy:
// - maxConcurrency <= 1: strictly sequential, no goroutines
// spawned (matches plan §"Concurrency policy" and the P0
// acceptance criterion "no goroutine spawns for 0 or 1").
-// - maxConcurrency > 1: bounded fan-out via a buffered channel
-// semaphore of size maxConcurrency. The first item runs on
-// the main goroutine; subsequent items run in worker
-// goroutines that acquire the semaphore before invoking.
+// - maxConcurrency > 1: a fixed worker count processes queued
+// items, so blocked work does not delay admission or create
+// one goroutine per item.
//
// Per-item panics are recovered and surfaced as a normal error
// wrapped with "item %d:" so the outer lambda never crashes.
@@ -700,25 +698,36 @@ func runParallelFanout[I, O any](
return resultCh
}
- // Concurrent path. Use a buffered channel semaphore.
- sem := make(chan struct{}, options.maxConcurrency)
+ // Keep the pending queue no larger than the active worker count.
+ workers := min(options.maxConcurrency, len(indices))
+ jobs := make(chan int, workers)
var wg sync.WaitGroup
- for i, idx := range indices {
- wg.Add(1)
- idx := idx
- if i == 0 {
- // First task runs on the main goroutine.
- runOne(idx)
- wg.Done()
- continue
- }
- go func() {
- defer wg.Done()
- sem <- struct{}{}
- defer func() { <-sem }()
- runOne(idx)
- }()
+ for range workers {
+ wg.Go(func() {
+ for idx := range jobs {
+ if err := ctx.Err(); err != nil {
+ resultCh <- parallelTaskResult{index: idx, err: err}
+ continue
+ }
+ runOne(idx)
+ }
+ })
}
+ wg.Go(func() {
+ defer close(jobs)
+ for _, idx := range indices {
+ if err := ctx.Err(); err != nil {
+ resultCh <- parallelTaskResult{index: idx, err: err}
+ return
+ }
+ select {
+ case jobs <- idx:
+ case <-ctx.Done():
+ resultCh <- parallelTaskResult{index: idx, err: ctx.Err()}
+ return
+ }
+ }
+ })
go func() {
wg.Wait()
close(resultCh)
diff --git a/internal/agent/workflowx/parallel_test.go b/internal/agent/workflowx/parallel_test.go
index d388a2e54a..b75178ca48 100644
--- a/internal/agent/workflowx/parallel_test.go
+++ b/internal/agent/workflowx/parallel_test.go
@@ -189,9 +189,8 @@ func TestParallel_Sequential_OneGoroutineSpawns(t *testing.T) {
}
}
-// TestParallel_Concurrent_UsesSemaphoreFanout asserts that
-// MaxConcurrency(N) drives the fan-out path (i>=1 items run
-// via the semaphore-bounded goroutine fan-out). The eino
+// TestParallel_Concurrent_BoundedFanout asserts that
+// MaxConcurrency(N) drives the fan-out path. The eino
// Workflow runtime internally serialises Invoke calls on a
// single compiled runnable, so we cannot directly observe
// in-flight workers from outside; instead we drive
@@ -200,14 +199,12 @@ func TestParallel_Sequential_OneGoroutineSpawns(t *testing.T) {
// closes, and (c) the order in which the results arrive is
// still index-keyed (so the bounded fan-out did not lose
// per-item attribution).
-func TestParallel_Concurrent_UsesSemaphoreFanout(t *testing.T) {
+func TestParallel_Concurrent_BoundedFanout(t *testing.T) {
var calls atomic.Int32
runner := testCountingRunnable{
fn: func(_ context.Context, in int, _ ...compose.Option) (int, error) {
calls.Add(1)
- // Tiny sleep so the semaphore workers have a
- // chance to interleave with the main-goroutine
- // item 0.
+ // Tiny sleep so workers have a chance to interleave.
time.Sleep(time.Millisecond)
return in, nil
},
@@ -247,6 +244,149 @@ func TestParallel_Concurrent_UsesSemaphoreFanout(t *testing.T) {
}
}
+func TestParallel_Concurrent_FirstItemDoesNotBlockAdmission(t *testing.T) {
+ firstStarted := make(chan struct{})
+ secondStarted := make(chan struct{})
+ releaseFirst := make(chan struct{})
+ release := sync.OnceFunc(func() { close(releaseFirst) })
+ defer release()
+ runner := testCountingRunnable{fn: func(_ context.Context, in int, _ ...compose.Option) (int, error) {
+ if in == 0 {
+ close(firstStarted)
+ <-releaseFirst
+ } else if in == 1 {
+ close(secondStarted)
+ }
+ return in, nil
+ }}
+ opts := getParallelOptions([]ParallelOption{WithParallelMaxConcurrency(2), WithParallelEnableSubCheckpoint(false)})
+ ch := make(chan (<-chan parallelTaskResult), 1)
+ go func() {
+ ch <- runParallelFanout(t.Context(), "par", runner, []int{0, 1}, []int{0, 1}, opts, newParallelBridgeState(nil))
+ }()
+ select {
+ case <-firstStarted:
+ case <-time.After(5 * time.Second):
+ t.Fatal("first item did not start")
+ }
+ select {
+ case <-secondStarted:
+ case <-time.After(200 * time.Millisecond):
+ t.Fatal("second item was blocked behind first")
+ }
+ release()
+ select {
+ case results := <-ch:
+ for range results {
+ }
+ case <-time.After(5 * time.Second):
+ t.Fatal("fanout did not return")
+ }
+}
+
+func TestParallel_Concurrent_BoundsWaitingGoroutines(t *testing.T) {
+ const count = 512
+ firstStarted := make(chan struct{})
+ releaseFirst := make(chan struct{})
+ releaseRest := make(chan struct{})
+ releaseFirstOnce := sync.OnceFunc(func() { close(releaseFirst) })
+ defer releaseFirstOnce()
+ release := sync.OnceFunc(func() { close(releaseRest) })
+ defer release()
+ runner := testCountingRunnable{fn: func(_ context.Context, in int, _ ...compose.Option) (int, error) {
+ if in == 0 {
+ close(firstStarted)
+ <-releaseFirst
+ } else {
+ <-releaseRest
+ }
+ return in, nil
+ }}
+ items := make([]int, count)
+ indices := make([]int, count)
+ for i := range items {
+ items[i], indices[i] = i, i
+ }
+ opts := getParallelOptions([]ParallelOption{WithParallelMaxConcurrency(2), WithParallelEnableSubCheckpoint(false)})
+ before := runtime.NumGoroutine()
+ ch := make(chan (<-chan parallelTaskResult), 1)
+ go func() {
+ ch <- runParallelFanout(t.Context(), "par", runner, items, indices, opts, newParallelBridgeState(nil))
+ }()
+ select {
+ case <-firstStarted:
+ case <-time.After(5 * time.Second):
+ t.Fatal("first item did not start")
+ }
+ releaseFirstOnce()
+ var results <-chan parallelTaskResult
+ select {
+ case results = <-ch:
+ case <-time.After(5 * time.Second):
+ t.Fatal("fanout did not return")
+ }
+ if got := runtime.NumGoroutine(); got > before+50 {
+ t.Errorf("fanout started %d extra goroutines for concurrency 2", got-before)
+ }
+ release()
+ for range results {
+ }
+}
+
+func TestParallel_Concurrent_CancelSkipsQueuedItems(t *testing.T) {
+ const count = 128
+ ctx, cancel := context.WithCancel(t.Context())
+ defer cancel()
+ started := make(chan struct{}, 2)
+ var calls atomic.Int32
+ runner := testCountingRunnable{fn: func(ctx context.Context, in int, _ ...compose.Option) (int, error) {
+ calls.Add(1)
+ select {
+ case started <- struct{}{}:
+ default:
+ }
+ <-ctx.Done()
+ return 0, ctx.Err()
+ }}
+ items := make([]int, count)
+ indices := make([]int, count)
+ for i := range items {
+ items[i], indices[i] = i, i
+ }
+ opts := getParallelOptions([]ParallelOption{WithParallelMaxConcurrency(2), WithParallelEnableSubCheckpoint(false)})
+ results := make(chan (<-chan parallelTaskResult), 1)
+ go func() {
+ results <- runParallelFanout(ctx, "par", runner, items, indices, opts, newParallelBridgeState(nil))
+ }()
+ for range 2 {
+ select {
+ case <-started:
+ case <-time.After(5 * time.Second):
+ t.Fatal("both workers did not start")
+ }
+ }
+ cancel()
+ var got <-chan parallelTaskResult
+ select {
+ case got = <-results:
+ case <-time.After(5 * time.Second):
+ t.Fatal("fanout did not return after cancellation")
+ }
+ seen := 0
+ for result := range got {
+ seen++
+ if !errors.Is(result.err, context.Canceled) {
+ t.Errorf("item %d: got %v, want cancellation", result.index, result.err)
+ }
+ }
+ if seen >= count {
+ t.Errorf("cancellation reported all %d items instead of stopping admission", seen)
+ }
+ if got := calls.Load(); got > 2 {
+ t.Errorf("invoked %d items after cancellation with concurrency 2", got)
+ }
+}
+
// TestParallel_SingleItemError_Wrapped asserts the "item %d: %w"
// wrapping The lambda must return the wrapped error,
// other items must be drained.