Skip to content
Tutorials Center
My learning

Topics

Lesson 102 of 182 ยท Async and Concurrency

Concurrent Collections

Learn the thread-safe collections in C# - ConcurrentDictionary and its GetOrAdd pitfall, ConcurrentQueue, ConcurrentBag, BlockingCollection, and immutable snapshots as an alternative to locking.

The normal collections, List<T>, Dictionary<TKey, TValue> and Queue<T>, are not thread-safe for writing. If two threads add to the same List<T> at once, items can be lost, the internal array can be corrupted, or an exception can be thrown. You could wrap every access in a lock, but .NET also ships collections that are designed for concurrent use: the types in System.Collections.Concurrent.

This lesson covers ConcurrentDictionary, ConcurrentQueue, ConcurrentStack, ConcurrentBag, and BlockingCollection, plus the single most common bug (a check-then-act on a thread-safe collection), and the alternative of avoiding shared mutation altogether with immutable data.

Concurrent collections make each individual operation safe. They do not make a sequence of operations safe. "If the key is missing, add it" written as two calls is still a race. Every API on this page exists to do such compound steps atomically, so learn those methods rather than combining simple ones.

Why not just lock a normal collection?

A lock around a Dictionary works and is often the simplest correct choice. Concurrent collections shine when many threads use the collection at once: ConcurrentDictionary uses several internal locks (striped by hash bucket) and lock-free reads, so threads rarely block each other. The price is a bigger memory footprint and slower single-threaded use. If only one thread ever touches a collection, use the plain one.

ConcurrentDictionary

ConcurrentDictionary<TKey, TValue> is a hash table that many threads can read and write safely. Its indexer, TryGetValue, TryAdd, TryRemove and TryUpdate are all atomic. The most useful members do a compound operation as one step:

  • AddOrUpdate(key, addValue, updateFactory) inserts, or updates an existing value from its old value.
  • GetOrAdd(key, value) returns the existing value, or adds and returns the new one.
C# Counting words with AddOrUpdate

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Each of the 100 rounds adds "the" four times, so the total is 400 no matter how the rounds interleave. Compare this with if (!d.ContainsKey(w)) d[w] = 0; d[w]++; on a plain dictionary: that would lose counts or throw.

The update delegate of AddOrUpdate can run more than once for the same key. When a thread computes the new value and finds that another thread changed the entry in the meantime, it retries with the fresh old value. Keep the delegate pure: no side effects, no I/O, no increments of outside counters.

The check-then-act trap

Because each call is atomic but the pair is not, this code is wrong even with a concurrent dictionary:

C#
// BROKEN: two threads can both see "missing" and both add
if (!cache.ContainsKey(id))
{
    cache[id] = Load(id);
}

Use GetOrAdd, TryAdd or AddOrUpdate instead, since the check and the write happen inside the collection.

The GetOrAdd pitfall

GetOrAdd(key, factory) takes a delegate that creates the value when the key is missing. Here is the surprise: the factory runs outside the dictionary's lock. If two threads miss the same key at the same moment, both run the factory, and the dictionary keeps only one of the two results. The other is silently discarded. If the factory is expensive or has a side effect (opening a connection, writing a file), you pay twice.

The example below forces the worst case on purpose: a Barrier makes both threads wait inside the factory until the other one arrives, so both factory calls are guaranteed to be in flight together.

C# GetOrAdd may call the factory twice

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

In real programs the overlap is rare, so the bug is rare, which makes it hard to notice. The standard fix is to store a Lazy<T> instead of the value. Two Lazy<T> wrappers may be created, but only the one that ends up in the dictionary is ever asked for its Value, and Lazy<T> runs its factory exactly once.

C# Lazy makes the factory run once

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

For async factories the same idea works with Lazy<Task<T>> (or store the Task<T> itself), so concurrent callers share one in-flight operation. If the task can fail, remember to evict it so a failure is not cached forever.

Other useful members

TryRemove(key, out value) removes and returns in one step. TryUpdate(key, newValue, comparisonValue) replaces only if the current value equals the one you expect, the dictionary version of CompareExchange. Enumerating (foreach) is safe while other threads write; you get a snapshot-like view that may or may not include concurrent changes, and it never throws. Count, Keys and Values lock the whole table and copy, so avoid calling them in hot paths.

ConcurrentQueue and ConcurrentStack

ConcurrentQueue<T> is a first-in, first-out queue that is safe for many producers and consumers. Enqueue always succeeds. Because another thread may take the last item between your check and your read, there is no safe "peek then dequeue": use TryDequeue, which returns false if the queue is empty.

C# ConcurrentQueue with several producers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Items from the same producer stay in order relative to each other, but items from different producers interleave arbitrarily, which is why the example sorts before printing. ConcurrentStack<T> is the last-in, first-out version (Push, TryPop, PushRange).

ConcurrentBag

ConcurrentBag<T> is an unordered collection that is optimized for the case where the same thread both adds and takes items: each thread has its own local list, so adding rarely touches shared memory. It has no useful order and no way to remove a specific item. It suits object pools and "collect results from many workers, then read them all" jobs.

C# Collecting results in a ConcurrentBag

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

If you only need to gather results, another option is to preallocate an array and write by index (see Parallel and PLINQ), which keeps the order and needs no concurrent collection at all.

BlockingCollection: producer-consumer with waiting

Producers and consumers rarely run at the same speed. A BlockingCollection<T> wraps a concurrent collection (a queue by default) and adds two powers:

  • consumers block (wait) when it is empty, instead of spinning;
  • with a bounded capacity, producers block when it is full, which slows a fast producer down to the consumer's pace. This is called back-pressure.

A producer calls CompleteAdding() when there will be no more items, and consumers loop with GetConsumingEnumerable(), which ends once the collection is empty and completed.

C# A bounded BlockingCollection

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

The two consumers split the 20 jobs between them in an unpredictable way, but the sum is the same every time. BlockingCollection blocks threads while it waits. That is fine for dedicated worker threads, but in async code it wastes pool threads; the modern replacement is Channels, which wait with await instead.

Immutable data as a strategy

The simplest way to make shared data safe is to never change it. If an object cannot be modified after creation, any number of threads can read it with no locking. To "change" it you build a new object and publish it by swapping one reference. Readers always see either the complete old version or the complete new one.

The System.Collections.Immutable types (ImmutableList<T>, ImmutableDictionary<TKey, TValue>, ImmutableArray<T>) are built in; ImmutableInterlocked gives you atomic updates for them.

C# Immutable snapshots with ImmutableInterlocked

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Update works like the CompareExchange loop in lock, Lock and Interlocked: compute a new list from the current one and swap it in, retrying if another thread got there first. (So, as with AddOrUpdate, the lambda may run more than once and must be free of side effects.) Immutable collections allocate on every change, so they fit data that is read often and changed rarely, such as configuration, routing tables or subscriber lists. For write-heavy data prefer a concurrent collection.

Choosing a collection

Need Use
Shared lookup table, many writers ConcurrentDictionary
Work items, FIFO ConcurrentQueue, or a Channel when async
LIFO ConcurrentStack
Gather unordered results ConcurrentBag, or an array written by index
Blocking hand-off with limits (threads) BlockingCollection
Async hand-off with limits Channel<T> (Channels)
Read-mostly shared data Immutable collections + ImmutableInterlocked
Single-threaded code Plain List, Dictionary

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why is if (!d.ContainsKey(k)) d[k] = v; still a race on a ConcurrentDictionary?

    The check and the write are separate operations. Use TryAdd, GetOrAdd or AddOrUpdate so they happen as one step.
  2. 2. What can happen when two threads call GetOrAdd(key, factory) for the same missing key?

    The factory runs outside the dictionary's lock. Wrap values in Lazy<T> if the factory must run only once.
  3. 3. How does a consumer know a BlockingCollection has no more items coming?

    Count can be zero temporarily. CompleteAdding marks the end, and GetConsumingEnumerable finishes when the collection is empty and completed.
  4. 4. What does a bounded capacity on a BlockingCollection give you?

    A full collection makes Add block, which slows a fast producer to the consumers' pace and caps memory use.
  5. 5. Which approach lets many threads read a configuration object without any lock?

    Immutable objects cannot change under a reader. Writers publish a new instance with an atomic reference swap.

Summary

  • List<T> and Dictionary<TKey, TValue> are not safe for concurrent writes; System.Collections.Concurrent provides collections that are.
  • Concurrent collections make single operations atomic, not sequences: use GetOrAdd, AddOrUpdate, TryAdd, TryRemove and TryDequeue instead of check-then-act.
  • GetOrAdd and AddOrUpdate delegates can run more than once; keep them free of side effects, or store Lazy<T> values to run an expensive factory exactly once.
  • ConcurrentQueue/ConcurrentStack give FIFO/LIFO, ConcurrentBag is unordered, and BlockingCollection adds blocking waits and bounded capacity.
  • Immutable collections with atomic swaps remove the need for locks on read-mostly data; for async producer-consumer prefer channels.

Next: Channels and Producer-Consumer