System.Collections.Concurrent.ConcurrentDictionary<TKey,TValue> Class

Represents a thread-safe collection of key/value pairs that can be accessed by multiple threads concurrently.

See Also: ConcurrentDictionary<TKey,TValue> Members

Syntax

[System.Diagnostics.DebuggerDisplay("Count={Count}")]
[System.Diagnostics.DebuggerTypeProxy(typeof(System.Collections.Generic.CollectionDebuggerView`2))]
public class ConcurrentDictionary<TKey, TValue> : ICollection<KeyValuePair<TKey, TValue>>, IDictionary<TKey, TValue>, IEnumerable<KeyValuePair<TKey, TValue>>, IDictionary

Type Parameters

TKey
Documentation for this section has not yet been entered.
TValue
Documentation for this section has not yet been entered.

Remarks

For very large System.Collections.Concurrent.ConcurrentDictionary`2 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 Dictionary`2 class, System.Collections.Concurrent.ConcurrentDictionary`2 implements the IDictionary`2 interface. In addition, System.Collections.Concurrent.ConcurrentDictionary`2 provides several methods for adding or updating key/value pairs in the dictionary, as described in the following table.

Add a new key to the dictionary, if it doesn’t already exist in the dictionary

ConcurrentDictionary`2.TryAdd(`0, `1)

This method adds the specified key/value pair, if the key doesn’t currently exist in the dictionary. The method returns true or false depending on whether the new pair was added.

Update the value for an existing key in the dictionary, if that key has a specific value

ConcurrentDictionary`2.TryUpdate(`0, `1, `1)

This method checks whether the key has a specified value, and if it does, updates the key with a new value. It's similar to the erload:System.Threading.Interlocked.CompareExchange method, except that it's used for dictionary elements.

Store a key/value pair in the dictionary unconditionally, and overwrite the value of a key that already exists

The indexer’s setter: dictionary[key] = newValue

Add a key/value pair to the dictionary, or if the key already exists, update the value for the key based on the key’s existing value

ConcurrentDictionary`2.AddOrUpdate(`0, `1, Func<`0, `1, `1>)

—or—

ConcurrentDictionary`2.AddOrUpdate(`0, Func<`0, `1>, Func<`0, `1, `1>)

ConcurrentDictionary`2.AddOrUpdate(`0, `1, Func<`0, `1, `1>) accepts the key and two delegates. It uses the first delegate if the key doesn’t exist in the dictionary; it accepts the key and returns the value that should be added for the key. It uses the second delegate if the key does exist; it accepts the key and its current value, and it returns the new value that should be set for the key.

ConcurrentDictionary`2.AddOrUpdate(`0, Func<`0, `1>, Func<`0, `1, `1>) accepts the key, a value to add, and the update delegate. This is the same as the previous overload, except that it doesn't use a delegate to add a key.

Get the value for a key in the dictionary, adding the value to the dictionary and returning it if the key doesn’t exist

ConcurrentDictionary`2.GetOrAdd(`0, `1)

—or—

ConcurrentDictionary`2.GetOrAdd(`0, Func<`0, `1>)

These overloads provide lazy initialization for a key/value pair in the dictionary, adding the value only if it’s not there.

ConcurrentDictionary`2.GetOrAdd(`0, `1) takes the value to be added if the key doesn’t exist.

ConcurrentDictionary`2.GetOrAdd(`0, Func<`0, `1>) takes a delegate that will generate the value if the key doesn’t exist.

All these operations are atomic and are thread-safe with regards to all other operations on the System.Collections.Concurrent.ConcurrentDictionary`2 class. The only exceptions are the methods that accept a delegate, that is, erload:System.Collections.Concurrent.ConcurrentDictionary`2.AddOrUpdate and erload:System.Collections.Concurrent.ConcurrentDictionary`2.GetOrAdd. For modifications and write operations to the dictionary, System.Collections.Concurrent.ConcurrentDictionary`2 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.

Requirements

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