Parallel.Foreach

Parallel.For() is designed for efficiently processing ranges of numbers. Parallel.ForEach(), found in the same System.Threading.Tasks namespace, is designed for collections: anything that implements IEnumerable<T>.

The method takes an IEnumerable<T> instance as its first parameter and executes an Action<T> delegate for each item in the enumeration. Instead of receiving a numeric index, your delegate receives the item itself, which makes it the natural choice for iterating over file paths, database query results, customer objects, or any other set of data.

If the source is an array or a List<T>, the framework uses direct indexing to create partitions efficiently. For any other kind of enumeration, a Partitioner instance decides how the items are handed out to the worker threads. Either way, every item in the collection is processed exactly once, but the items are processed in parallel to maximize performance.

Two behaviors are important to remember from the start:

1. Parallel.ForEach() gives no guarantee about the order of execution. The items may be processed in any order, and that order changes from run to run.
2. The call is blocking: the thread that calls Parallel.ForEach() waits until every item has been processed (or until the loop is stopped or cancelled).

This article follows an easy-to-harder path with six examples:

1. Step 1: the simplest loop over a List<string>.
2. Step 2: the richer delegate signatures – ParallelLoopState and the item index – and stopping the loop early.
3. Step 3: limiting how many items may be processed together with ParallelOptions.MaxDegreeOfParallelism.
4. Step 4: stopping the loop from the outside with a CancellationToken.
5. Step 5: looping over a lazy IEnumerable and over an explicitly created Partitioner.
6. Step 6: a normal foreach loop and a Parallel.ForEach loop doing the same CPU-heavy work, with their run times compared.

Features and Design

The most basic syntax involves passing an IEnumerable<T> instance as the first parameter and an Action<T> delegate as the second parameter:

1. source – the collection whose items must be processed.
2. body – the delegate that is called exactly once for every item.

The delegate can simply receive the element to process, or it can receive more parameters. These are the possible signatures for the Action delegate:

1. (T) – the variable contains the current element being processed.
2. (T, ParallelLoopState) – the element and a ParallelLoopState instance, used to safely stop the loop.
3. (T, ParallelLoopState, long) – the element, a ParallelLoopState, and a state parameter that defaults to the index of the current item in the enumeration.

The method returns a ParallelLoopResult structure. Its IsCompleted property is true when every item was processed and the loop was not stopped early.

A ParallelOptions parameter can be passed to provide cancellation support, maximum degree of parallelism control, and a custom task scheduler, exactly the same as with Parallel.For():

1. MaxDegreeOfParallelism – the maximum number of items allowed to be processed at the same time. The default is -1, which means "no upper limit, let .NET decide". Setting it to 1 makes the loop behave like a sequential foreach loop.
2. CancellationToken – a token that can stop the loop from the outside. The default is CancellationToken.None, which means the loop is never cancelled.
3. TaskScheduler – a custom scheduler, or null to use the default scheduler.

Finally, remember that the Parallel class synchronizes its own internal bookkeeping but provides no synchronization at all for the data your delegate touches. Any shared variable, collection or file accessed from the loop body still needs a lock, an Interlocked method, or a thread-safe collection such as ConcurrentBag<T>.

Key Differences from Parallel.For

The two parallel loops are similar in many respects, but there are some key differences:

Parallel.For() iterates over a numeric range, such as a specified "from" and "to" range of integers, and provides the current index as the loop variable. This is particularly useful for numeric processing tasks: operations on arrays or matrices where calculations depend on the index, or transformations of elements in a computational grid.

Parallel.ForEach() processes collections such as List, Array, or any IEnumerable, and provides the current element as the loop variable. This makes it ideal for non-numeric data or large sets of objects: iterating over file paths, applying operations to database query results, or transforming objects in a collection.

Step 1: Code Example – The Simplest Parallel.ForEach Loop

How It Works

1. A List<string> with six city names is the source collection. Because a list is indexable, .NET can split it into chunks by simple index arithmetic, without any partitioner machinery.
2. The delegate has the simplest possible shape, Action<string>: it receives one city name and does something with it. Each name is passed to the delegate exactly once.
3. Printing happens inside the loop body on purpose, so the mixed order is visible. The names do not come out in the order Rome, Oslo, Lima, Cairo, Tokyo, Paris, and the order is different on every run.
4. Environment.CurrentManagedThreadId reveals which thread processed each item. Several different ids appear, and the calling thread (usually id 1) also takes part, because it helps with the work instead of just waiting.
5. The last line runs only after every item is done, because Parallel.ForEach() blocks. result.IsCompleted is True since nothing stopped the loop early.

Sample Output

Both the order of the names and the thread ids change on every run and on every machine. Notice that one thread often handles several items: it received a whole chunk of the list.

Step 2: Code Example – ParallelLoopState and the Item Index

How It Works

1. The delegate uses the third signature, (T, ParallelLoopState, long). The index parameter tells you where the item sits in the source collection, which the item itself cannot tell you.
2. When the wanted file is found, loopState.Stop() is called. This asks the loop to end as soon as possible: items that are already running still finish, but no new item is started.
3. Break() is the alternative. It also ends the loop, but it promises that every item positioned before the current index is still processed. Stop() makes no such promise, which is why it is the right choice for a "find the first match" search.
4. Other iterations check loopState.IsStopped and return immediately, so no time is wasted on work whose result nobody needs.
5. result.IsCompleted is False. That is the standard way to detect that a parallel loop exited early instead of processing the whole collection.

Sample Output

How many items are checked before the match is found is unpredictable: it depends on which chunks the threads received and how fast they ran. The one guaranteed line is the "Found" message.

Step 3: Code Example – Limiting Parallelism with ParallelOptions

How It Works

1. A ParallelOptions instance with MaxDegreeOfParallelism = 2 is passed as the second parameter, so at most two items may be inside the delegate at any moment.
2. Each item increases a shared runningCount when it starts and decreases it when it ends. Interlocked.Increment and Interlocked.Decrement change the value in one uninterruptible step, so no update is lost.
3. InterlockedMax remembers the largest value runningCount ever reached. It uses Interlocked.CompareExchange, which writes the new value only if the field still holds the value the method last read; otherwise it tries again with the fresh value.
4. The 100 ms sleep represents work. Without it, an item would be finished before the next one started and the overlap could not be measured.
5. The reported maximum is 2, which proves the limit was respected. This is exactly how you protect an external service that cannot handle unlimited concurrent calls.

Sample Output

Step 4: Code Example – Cancelling a Parallel.ForEach Loop

How It Works

1. A CancellationTokenSource creates the token and decides when the cancellation happens. CancelAfter(150) starts a timer that cancels the token after 150 milliseconds.
2. The token is placed into ParallelOptions.CancellationToken. From that moment the loop checks the token while it works and refuses to start further items once it is cancelled.
3. The loop is asked to process 100 items, each sleeping 100 ms, two at a time. That would take roughly five seconds, so the cancellation always wins and only a handful of items complete.
4. Parallel.ForEach() then throws OperationCanceledException. Note that it is caught directly, not through an AggregateException. Items already being processed are not killed; they finish their current work first.
5. This is cancellation from outside the loop. ParallelLoopState.Stop() from Step 2 is the way to end the loop from inside it, and it does not throw.

Sample Output

Step 5: Code Example – A Lazy IEnumerable and a Partitioner

How It Works

1. ReadSensorIds() is a generator method built with yield return. It has no Count and no indexer, so .NET cannot simply cut it into equal slices the way it does with an array or a list.
2. For such a source, Parallel.ForEach() automatically uses a system-provided Partitioner. The partitioner reads the sequence and hands the items out to the worker threads as they become available. Every item is still processed exactly once.
3. The second loop creates the partitioner explicitly with Partitioner.Create(source, options) and passes it in place of the collection. This is the hook you use when the default strategy is not a good fit.
4. EnumerablePartitionerOptions.NoBuffering means one item at a time per thread. The default (None) lets a thread grab a small batch, which is faster when the body is very short but can leave other threads idle when some items are much slower than others.
5. For advanced scenarios you can write your own class deriving from Partitioner<T> or OrderablePartitioner<T> to fine-tune performance, but the built-in partitioners are optimized for most general use cases.

Sample Output

The counters are always 6 in both loops, which proves the promise of the method: each item is processed exactly once, no matter which partitioning strategy is used. Only the order and the thread ids differ.

Step 6: Code Example – Normal foreach Loop vs Parallel.ForEach

How It Works

1. The unit of work is CountPrimesBelow(200000), a purely CPU-bound calculation that uses only local variables, so it is safe to run on many threads at the same time.
2. The first loop is an ordinary foreach loop: the eight items are processed one after another on a single thread, and a Stopwatch measures the total time.
3. The second loop is a Parallel.ForEach over the same list. .NET splits the items into chunks and runs them on several thread pool threads, so multiple processor cores work at the same time.
4. The parallel results go into a ConcurrentBag<int>, not a List<int>. Several threads add at the same moment, and List<T> is not thread-safe: it would silently lose items or throw an exception. This is the reminder that the loop body must protect its own shared data.
5. Both sequences are sorted before they are compared, because the order inside the bag is unpredictable. The values themselves are identical: parallel execution changes the timing and the order, never the results of an independent calculation.

Sample Output

The measured times depend on the machine. The speed-up is limited by the number of processor cores, and it can never be larger than that number, because there are only so many cores to share the work.

When to Use

Use Parallel.ForEach() when:

1. The data lives in a collection – an array, a List<T>, a query result, or any other IEnumerable<T> – rather than in a numeric range.
2. The items are independent: processing one item does not need the result of another and the order does not matter.
3. The work for each item is CPU-bound and heavy enough that splitting it is worth the extra cost of scheduling threads.

Avoid it when:

1. The loop body is very short (for example adding two numbers). Starting and coordinating threads then costs more than the loop itself, and the parallel version becomes slower.
2. The items depend on each other or must be processed in a fixed order.
3. The work is I/O-bound, such as calling web services or reading files. In that case async/await with Task.WhenAll, or Parallel.ForEachAsync(), is a better fit, because those do not block threads while waiting.
4. Every item hits the same shared object anyway. If almost all of the work happens inside a lock, the threads simply wait for each other and nothing is gained.

Related members are Parallel.For() for numeric ranges, Parallel.ForEachAsync() for asynchronous work per item, Parallel.Invoke() for a fixed set of different actions, and PLINQ (AsParallel()) for query-style processing.