System.Collections.Concurrent.BlockingCollection<T> Class

Provides blocking and bounding capabilities for thread-safe collections that implement System.Collections.Concurrent.IProducerConsumerCollection`1.

See Also: BlockingCollection<T> Members

Syntax

[System.Diagnostics.DebuggerDisplay("Count={Count}")]
[System.Diagnostics.DebuggerTypeProxy(typeof(System.Collections.Generic.CollectionDebuggerView`1))]
[System.Runtime.InteropServices.ComVisible(false)]
public class BlockingCollection<T> : IEnumerable<T>, ICollection, IDisposable

Type Parameters

T
Documentation for this section has not yet been entered.

Remarks

System.Collections.Concurrent.BlockingCollection`1 is a thread-safe collection class that provides the following:

System.Collections.Concurrent.IProducerConsumerCollection`1 represents a collection that allows for thread-safe adding and removal of data. System.Collections.Concurrent.BlockingCollection`1 is used as a wrapper for an System.Collections.Concurrent.IProducerConsumerCollection`1 instance, and allows removal attempts from the collection to block until data is available to be removed. Similarly, you can create a System.Collections.Concurrent.BlockingCollection`1 to enforce an upper bound on the number of data elements allowed in the System.Collections.Concurrent.IProducerConsumerCollection`1; addition attempts to the collection may then block until space is available to store the added items. In this manner, System.Collections.Concurrent.BlockingCollection`1 is similar to a traditional blocking queue data structure, except that the underlying data storage mechanism is abstracted away as an System.Collections.Concurrent.IProducerConsumerCollection`1.

System.Collections.Concurrent.BlockingCollection`1 supports bounding and blocking. Bounding means that you can set the maximum capacity of the collection. Bounding is important in certain scenarios because it enables you to control the maximum size of the collection in memory, and it prevents the producing threads from moving too far ahead of the consuming threads.Multiple threads or tasks can add items to the collection concurrently, and if the collection reaches its specified maximum capacity, the producing threads will block until an item is removed. Multiple consumers can remove items concurrently, and if the collection becomes empty, the consuming threads will block until a producer adds an item. A producing thread can call the BlockingCollection`1.CompleteAdding method to indicate that no more items will be added. Consumers monitor the BlockingCollection`1.IsCompleted property to know when the collection is empty and no more items will be added.

BlockingCollection`1.Add(`0) and BlockingCollection`1.Take operations are typically performed in a loop. You can cancel a loop by passing in a System.Threading.CancellationToken object to the BlockingCollection`1.TryAdd(`0) or BlockingCollection`1.TryTake(`0@) method, and then checking the value of the token's System.Threading.CancellationToken.IsCancellationRequested property on each iteration. If the value is true, it is up to you to respond the cancellation request by cleaning up any resources and exiting the loop.

When you create a System.Collections.Concurrent.BlockingCollection`1 object, you can specify not only the bounded capacity but also the type of collection to use. For example, you could specify a System.Collections.Concurrent.ConcurrentQueue`1 object for first in, first out (FIFO) behavior, or a System.Collections.Concurrent.ConcurrentStack`1 object for last in, first out (LIFO) behavior. You can use any collection class that implements the System.Collections.Concurrent.IProducerConsumerCollection`1 interface. The default collection type for System.Collections.Concurrent.BlockingCollection`1 is System.Collections.Concurrent.ConcurrentQueue`1.

Do not modify the underlying collection directly. Use System.Collections.Concurrent.BlockingCollection`1 methods to add or remove elements. The System.Collections.Concurrent.BlockingCollection`1 object can become corrupted if you change the underlying collection directly.

Requirements

Namespace: System.Collections.Concurrent
Assembly: System (in System.dll)
Assembly Versions: 4.0.0.0