ConcurrentDictionary<TKey, TValue> Class

For very large ConcurrentDictionary<TKey, TValue> objects, you can increase the maximum array size to 2 gigabytes (GB) on a 64-bit system by setting the <gcAllowVeryLargeObjects> configuration element to true in the run-time environment.

Like the System.Collections.Generic.Dictionary<TKey, TValue> class, ConcurrentDictionary<TKey, TValue> implements the IDictionary<TKey, TValue> interface. In addition, ConcurrentDictionary<TKey, TValue> provides several methods for adding or updating key/value pairs in the dictionary, as described in the following table.

All these operations are atomic and are thread-safe with regards to all other operations on the ConcurrentDictionary<TKey, TValue> class. The only exceptions are the methods that accept a delegate, that is, AddOrUpdate and GetOrAdd. For modifications and write operations to the dictionary, ConcurrentDictionary<TKey, TValue> uses fine-grained locking to ensure thread safety. (Read operations on the dictionary are performed in a lock-free manner.) However, delegates for these methods are called outside the locks to avoid the problems that can arise from executing unknown code under a lock. Therefore, the code executed by these delegates is not subject to the atomicity of the operation.

Note

The HostProtectionAttribute attribute applied to this type or member has the following Resources property value: Synchronization | ExternalThreading. The HostProtectionAttribute does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the HostProtectionAttribute class or SQL Server Programming and Host Protection Attributes.

The following example shows how to construct a ConcurrentDictionary<TKey, TValue> object.

class CD_Ctor
{
        // Demonstrates: 
        //      ConcurrentDictionary<TKey, TValue> ctor(concurrencyLevel, initialCapacity) 
        //      ConcurrentDictionary<TKey, TValue>[TKey] 
        static void Main()
        {
            // We know how many items we want to insert into the ConcurrentDictionary. 
            // So set the initial capacity to some prime number above that, to ensure that 
            // the ConcurrentDictionary does not need to be resized while initializing it. 
            int NUMITEMS = 64;
            int initialCapacity = 101;

            // The higher the concurrencyLevel, the higher the theoretical number of operations 
            // that could be performed concurrently on the ConcurrentDictionary.  However, global 
            // operations like resizing the dictionary take longer as the concurrencyLevel rises.  
            // For the purposes of this example, we'll compromise at numCores * 2. 
            int numProcs = Environment.ProcessorCount;
            int concurrencyLevel = numProcs * 2;

            // Construct the dictionary with the desired concurrencyLevel and initialCapacity
            ConcurrentDictionary<int, int> cd = new ConcurrentDictionary<int, int>(concurrencyLevel, initialCapacity);

            // Initialize the dictionary 
            for (int i = 0; i < NUMITEMS; i++) cd[i] = i * i;

            Console.WriteLine("The square of 23 is {0} (should be {1})", cd[23], 23 * 23);
        }
}

.NET Framework

.NET Framework Client Profile

Portable Class Library

.NET for Windows Store apps

Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

All public and protected members of ConcurrentDictionary<TKey, TValue> are thread-safe and may be used concurrently from multiple threads.

Reference

Other Resources