In .NET, how do Parallel.ForEach and Parallel.ForEachAsync differ for an image-resizing job, including each one's default degree of parallelism?
answer
- blocking call vs returned Task
- Action<T> vs ValueTask-returning body
- minus one means no upper bound
- processor count when nothing is set
basics
~20 sParallel.ForEach blocks the caller, runs an Action<T> per item on pool threads plus the calling thread, and sets no upper bound on parallelism by default. Parallel.ForEachAsync (.NET 6) returns a Task, awaits a ValueTask-returning body and defaults to Environment.ProcessorCount.
solid answer
~50 s`Parallel.ForEach` is synchronous: the calling thread takes part as one worker and the call returns only when every iteration has finished, throwing an `AggregateException` if any failed. Its body is an `Action<T>`, and default `ParallelOptions` (`MaxDegreeOfParallelism = -1`) set no upper bound, so if bodies block, the loop also uses any extra threads the pool injects. It fits CPU-bound work such as decoding and resizing pixels already in memory. `Parallel.ForEachAsync`, added in .NET 6, returns a `Task`, takes a `Func<T, CancellationToken, ValueTask>` and runs at most `Environment.ProcessorCount` bodies at once unless you set `MaxDegreeOfParallelism`; the first failure cancels the token handed to the other bodies, and `await` rethrows the first exception. It fits bodies that await file or network I/O. An `async` lambda passed to `Parallel.ForEach` becomes `async void`, so the loop returns before the work is done.
code
csharp · 25 linesint running = 0, peak = 0;
await Parallel.ForEachAsync(Enumerable.Range(1, 200), async (id, ct) =>
{
int now = Interlocked.Increment(ref running);
InterlockedMax(ref peak, now);
await Task.Delay(20, ct); // stands in for reading or writing an image file
Interlocked.Decrement(ref running);
});
Console.WriteLine($"ForEachAsync peak={peak}, ProcessorCount={Environment.ProcessorCount}");
int finished = 0;
Parallel.ForEach(Enumerable.Range(1, 20), async id => // async lambda becomes async void
{
await Task.Delay(100);
Interlocked.Increment(ref finished);
});
Console.WriteLine($"Parallel.ForEach returned with {finished} of 20 items finished");
static void InterlockedMax(ref int target, int value)
{
int seen;
while (value > (seen = Volatile.Read(ref target)) &&
Interlocked.CompareExchange(ref target, value, seen) != seen) { }
}go deeper
Know that Parallel.ForEach blocks until every item is processed and that Parallel.ForEachAsync is the one to use when the body awaits something.
State both defaults precisely: no upper bound for Parallel.ForEach, Environment.ProcessorCount for ForEachAsync, and explain why an async lambda in Parallel.ForEach is async void.
Explain how a blocking body lets Parallel.ForEach soak up injected pool threads, how each loop reports failures, and why you set MaxDegreeOfParallelism explicitly in production jobs.
Connect the choice to the workload: CPU-bound loops are capped by cores, I/O-bound ones by what the storage or downstream service can take, and the cap belongs in configuration rather than a magic number.
## Two loops with different shapes Both methods live on `System.Threading.Tasks.Parallel` and both spread a collection's items over thread pool threads, but they are built for different kinds of body. | | `Parallel.ForEach` | `Parallel.ForEachAsync` | |---|---|---| | Returns | `ParallelLoopResult`, after all iterations end | a `Task` you await | | Body | `Action<T>` (overloads add `ParallelLoopState`, index, locals) | `Func<T, CancellationToken, ValueTask>` | | Default degree of parallelism | no upper bound (`MaxDegreeOfParallelism = -1`) | `Environment.ProcessorCount` | | Calling thread | runs iterations itself, then blocks | free while the loop runs | | Failures | `AggregateException` with one or more inner exceptions | task faults; `await` rethrows the first | ## `Parallel.ForEach`: synchronous data parallelism `Parallel.ForEach` splits the source into **partitions** and runs them on several workers at once. One worker is the calling thread itself: the loop runs its first replica synchronously and then waits for the rest, which is why it is a **blocking** call. The others are tasks on the default scheduler, so they run on thread pool threads. - **No cap by default.** `new ParallelOptions()` leaves `MaxDegreeOfParallelism` at `-1`, which the runtime source documents as no upper bound. For pure CPU work the thread count usually stays close to the core count, but if the body blocks on a lock or synchronous I/O, the loop picks up every extra thread the pool injects. In a test on a 14-core machine, a body that slept 100 ms reached 15 concurrent iterations. Set `MaxDegreeOfParallelism = Environment.ProcessorCount` (or lower) when you want a hard limit. - **Stopping early.** An overload with `ParallelLoopState` gives you `Stop()`, which tells the loop to start no more iterations, and `Break()`, which also stops new work but still runs every iteration with a lower index than the one that called it. Neither aborts iterations already running, and one loop may not use both. - **Failures.** After an iteration throws, the loop stops handing out new iterations, lets running ones finish, and throws an `AggregateException` holding every exception it collected. ## `Parallel.ForEachAsync`: async bodies, bounded by default `Parallel.ForEachAsync` arrived in .NET 6 for bodies that await. Each worker pulls the next item from the shared enumerator (behind an async lock), awaits your body, and loops; the source may be an `IEnumerable<T>` or an `IAsyncEnumerable<T>`. - **Bounded by default.** The runtime source sets the default degree of parallelism to `Environment.ProcessorCount`, and a negative `MaxDegreeOfParallelism` in `ParallelOptions` falls back to that same default rather than meaning unbounded. The snippet's 200 delayed bodies peaked at 14 concurrent on a 14-core machine. - **Failures.** The first exception is recorded and the loop cancels the `CancellationToken` it passes to every body, so cooperative bodies stop early and no new items are taken. When all workers finish, the returned task faults with the recorded exceptions; `await` rethrows the first, and `task.Exception` holds them all. If the token you passed in was cancelled, the task ends cancelled instead. ## The async-lambda trap `Parallel.ForEach(items, async item => { await ...; })` compiles, because an async lambda can convert to `Action<T>`. It becomes an **async void** delegate: each iteration returns to the loop at its first incomplete `await`, the loop finishes almost at once, and the rest of the work runs later with nobody watching. In the snippet, the loop returned with 0 of 20 items finished, and an exception thrown after the await would go unobserved by the loop and crash the process. The .NET docs on async lambda pitfalls point to `Parallel.ForEachAsync` instead. (How `async void` itself behaves belongs with the async lessons.) ## Choosing for the image job 1. **Images already in memory, resize is pure CPU:** `Parallel.ForEach` with `MaxDegreeOfParallelism` set to the core count. More threads than cores only adds context switching. 2. **Each item reads a file, resizes it and writes or uploads the result asynchronously:** `Parallel.ForEachAsync`, with a degree of parallelism chosen for the storage or network rather than the core count. 3. **A small fixed set of independent operations:** `Parallel.Invoke` or `Task.WhenAll`, not a loop. 4. **Never nest** a blocking `Parallel.ForEach` inside the async body, or wait on async work inside a `Parallel.ForEach` body; both block pool threads. The counting-loop siblings follow the same split: `Parallel.For` is synchronous and `Parallel.ForAsync` takes an async body.
- Why can a Parallel.ForEach with default options end up running more iterations at once than the machine has cores?Default `ParallelOptions` set `MaxDegreeOfParallelism` to -1, no upper bound, so the loop keeps offering work to the thread pool. When bodies block on I/O or locks, the pool's starvation logic injects extra threads and the loop uses them. Setting `MaxDegreeOfParallelism` caps it; for CPU-bound bodies the core count is the usual cap.
- In a .NET Parallel.For loop, how do ParallelLoopState.Break and ParallelLoopState.Stop differ?`Stop()` asks the loop to start no further iterations at all. `Break()` stops iterations beyond the current index but still completes every iteration with a lower index, and `ParallelLoopResult.LowestBreakIteration` reports where it broke. Neither interrupts iterations already running, which can check `IsStopped` or `ShouldExitCurrentIteration`, and mixing the two in one loop throws.
- Does passing ParallelOptions with MaxDegreeOfParallelism = -1 make Parallel.ForEachAsync unbounded?No. In the runtime source a negative degree falls back to the method's default, `Environment.ProcessorCount`; a run with -1 on a 14-core machine peaked at 14 concurrent bodies. To allow more concurrent I/O, set an explicit positive number.
- Parallel.ForEach defaults to Environment.ProcessorCount concurrent iterations
- Parallel.ForEachAsync has no default limit on concurrent bodies
- An async lambda in Parallel.ForEach makes the loop wait for each body
- Parallel.ForEach runs each item on a new dedicated thread
- ParallelLoopState.Stop aborts iterations that are already running