RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
refactor(workflow): bound parallel task admission (#20399)
Sbaaoui Idrissab30f51db9ae
diff --git a/internal/agent/workflowx/parallel.go b/internal/agent/workflowx/parallel.goindex 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.goindex 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.Int32runner := 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.