Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

ParallelLoopState Class

.NET Framework 4.6 and 4.5

Enables iterations of parallel loops to interact with other iterations. An instance of this class is provided by the Parallel class to each loop; you can not create instances in your code.

System::Object
  System.Threading.Tasks::ParallelLoopState

Namespace:  System.Threading.Tasks
Assemblies:   System.Threading.Tasks.Parallel (in System.Threading.Tasks.Parallel.dll)
  mscorlib (in mscorlib.dll)

public ref class ParallelLoopState

The ParallelLoopState type exposes the following members.

  NameDescription
Public propertySupported by Portable Class LibraryIsExceptionalGets whether any iteration of the loop has thrown an exception that went unhandled by that iteration.
Public propertySupported by Portable Class LibraryIsStoppedGets whether any iteration of the loop has called the Stop method.
Public propertySupported by Portable Class LibraryLowestBreakIterationGets the lowest iteration of the loop from which Break was called.
Public propertySupported by Portable Class LibraryShouldExitCurrentIterationGets whether the current iteration of the loop should exit based on requests made by this or other iterations.
Top

  NameDescription
Public methodSupported by Portable Class LibraryBreakCommunicates that the Parallel loop should cease execution of iterations beyond the current iteration at the system's earliest convenience.
Public methodSupported by Portable Class LibraryEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodSupported by Portable Class LibraryFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodSupported by Portable Class LibraryGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodSupported by Portable Class LibraryGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodSupported by Portable Class LibraryMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodSupported by Portable Class LibraryStopCommunicates that the Parallel loop should cease execution at the system's earliest convenience.
Public methodSupported by Portable Class LibraryToStringReturns a string that represents the current object. (Inherited from Object.)
Top

Note that you cannot instantiate an instance of this class. It is automatically generated by the compiler as an argument in a call to the Parallel::For or Parallel::ForEach method. The example provides an illustration.

Constructs such as for and foreach (in C#) and For and For Each (in Visual Basic) execute sequentially from the lowest index to the highest or from the first object in a set to the last. In contrast, the Parallel::For and Parallel::ForEach methods do not. Because individual iterations of the loop run in parallel, they can begin and end in any order. The ParallelLoopState class allows individual iterations of parallel loops to interact with one another. The ParallelLoopState class allows you to:

  • Exit the current iteration and prevent any additional iterations from starting by calling the Stop method. This does not affect iterations that have already begun execution.

  • Prevent any iterations with an index greater than the current index from executing by calling the Break method. This does not affect iterations that have already begun execution.

  • Determine whether an exception has occurred in any loop iteration by retrieving the value of the IsExceptional property.

  • Determine whether any iteration of the loop has called the Stop method by retrieving the value of the IsStopped property. You can use this property to return from iterations of the loop that started before the call to the Stop method but are still executing.

  • Determine whether any iteration of the loop has called the Break or Stopmethod or has thrown an exception by retrieving the value of the ShouldExitCurrentIteration property.

  • Exit from a long-running iteration whose index is greater than the index of an iteration in which Break was called by retrieving the value of the LowestBreakIteration property.

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 Break method is called. As the output from the example shows, no iterations whose index is greater than the LowestBreakIteration property value start after the call to the Break method.

No code example is currently available or this language may not be supported.

Because iterations of the loop are still likely to be executing when the Break method is called, each iteration calls the ShouldExitCurrentIteration property to check whether another iteration has called the Break method. If the property value is true, the iteration checks the value of the LowestBreakIteration property and, if it is greater than the current iteration's index value, returns immediately.

.NET Framework

Supported in: 4.6, 4.5, 4

.NET Framework Client Profile

Supported in: 4

.NET for Windows Phone apps

Supported in: Windows Phone 8.1

Portable Class Library

Supported in: Portable Class Library

A ParallelLoopState instance is meant to be used only within the body of the loop to which an instance was provided. It is not safe to use a provided ParallelLoopState instance after the associated loop ends, nor is it safe to explicitly hand it off to other threads and have those threads access it at any time. A different ParallelLoopState instance will be provided to each thread involved in a loop.

Show:
© 2015 Microsoft