Parallel::For Method (Int32, Int32, Action<Int32, ParallelLoopState^>^)
Executes a for (For in Visual Basic) loop in which iterations may run in parallel and the state of the loop can be monitored and manipulated.
Assembly: mscorlib (in mscorlib.dll)
public: static ParallelLoopResult For( int fromInclusive, int toExclusive, Action<int, ParallelLoopState^>^ body )
Parameters
- fromInclusive
-
Type:
System::Int32
The start index, inclusive.
- toExclusive
-
Type:
System::Int32
The end index, exclusive.
- body
-
Type:
System::Action<Int32, ParallelLoopState^>^
The delegate that is invoked once per iteration.
Return Value
Type: System.Threading.Tasks::ParallelLoopResultA structure that contains information about which portion of the loop completed.
| Exception | Condition |
|---|---|
| ArgumentNullException | The body argument is null. |
| AggregateException | The exception that contains all the individual exceptions thrown on all threads. |
The body delegate is invoked once for each value in the iteration range (fromInclusive, toExclusive). It is provided with two arguments:
An Int32 value that represents the iteration count.
A ParallelLoopState instance that can be used to break out of the loop prematurely. The ParallelLoopState object is created by the compiler; it cannot be instantiated in user code.
Calling the Break method informs the for operation that iterations after the current one don't have to execute. However, all iterations before the current one will still have to be executed if they haven't already.
Therefore, calling Break is similar to using a break operation within a conventional for loop in a language like C#, but it is not a perfect substitute: For example, there is no guarantee that iterations after the current one will definitely not execute.
If executing all iterations before the current one is not necessary, use the Stop method instead of using Break. Calling Stop informs the for loop that it may abandon all remaining iterations, regardless of whether they're before or after the current iteration, because all required work will have already been completed. However, as with Break, there are no guarantees regarding which other iterations will not execute.
If a loop is ended prematurely, the ParallelLoopResult structure that is returned will contain relevant information about the loop's completion.
If fromInclusive is greater than or equal to toExclusive, the method returns immediately without performing any iterations.
The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the ParallelLoopState::Break method is called. As the output from the example shows, no iterations whose index is greater than the ParallelLoopState::LowestBreakIteration property value start after the call to the ParallelLoopState::Break method.
Available since 8
.NET Framework
Available since 4.0
Portable Class Library
Supported in: portable .NET platforms
Windows Phone
Available since 8.1
Because iterations of the loop are still likely to be executing when the ParallelLoopState::Break method is called, each iteration calls the ParallelLoopState::ShouldExitCurrentIteration property to check whether another iteration has called the ParallelLoopState::Break method. If the property value is true, the iteration checks the value of the ParallelLoopState::LowestBreakIteration property and, if it is greater than the current iteration's index value, returns immediately.