When would you use ReaderWriterLockSlim, and what are its pitfalls compared with lock or immutable snapshots?

1. How it works internally (simplified)

state: reader count, writer flag, upgrader flag, waiting writers/readers/upgraders
EnterReadLock:    if no writer and no waiting writer -> readers++ ; else wait on read event
EnterWriteLock:   mark writer waiting; wait until readers == 0 and no writer -> writer = me
ExitWriteLock:    wake waiting writer first (writer preference), else release readers
EnterUpgradeable: only one upgrader; coexists with readers; can later EnterWriteLock (waits for other readers)

It tracks per-thread lock counts (for recursion policy and ownership checks), which is part of why it costs more than lock.

2. Upgradeable read pattern

_rw.EnterUpgradeableReadLock();
try
{
    if (!_index.TryGetValue(key, out var value))
    {
        _rw.EnterWriteLock();
        try { _index[key] = value = Build(key); }
        finally { _rw.ExitWriteLock(); }
    }
    return value;
}
finally { _rw.ExitUpgradeableReadLock(); }

Because only one thread can be in upgradeable mode, this path is serialised, even for cache hits. Often it's better to take a plain read lock for the hit path and fall back to a write lock (with a recheck) on a miss.

3. Why upgrading a plain read lock deadlocks

T1 holds read, wants write -> waits for readers == 0
T2 holds read, wants write -> waits for readers == 0
both wait for each other forever

That's why only one upgradeable reader is allowed, and why NoRecursion rejects read→write upgrades outright.

4. The snapshot pattern, done right

public sealed class RuleTable
{
    private FrozenDictionary<string, Rule> _rules = FrozenDictionary<string, Rule>.Empty;

    public Rule? Find(string key) =>
        Volatile.Read(ref _rules).GetValueOrDefault(key);   // grab the reference once, use it

    public void Reload(IEnumerable<Rule> rules)
    {
        var fresh = rules.ToFrozenDictionary(r => r.Key);   // build off to the side
        Volatile.Write(ref _rules, fresh);                    // publish atomically
    }

    public void Upsert(Rule rule)                              // several concurrent writers? use CAS
    {
        while (true)
        {
            var current = Volatile.Read(ref _rules);
            var copy = new Dictionary<string, Rule>(current) { [rule.Key] = rule };
            var next = copy.ToFrozenDictionary();
            if (Interlocked.CompareExchange(ref _rules, next, current) == current) return;
        }
    }
}

Rules: readers capture the reference once per operation; the published object is never mutated; multiple concurrent writers use Interlocked.CompareExchange (or a writer-only lock). Rebuilding a frozen dictionary is expensive, so this suits data that changes rarely; for frequent small updates, ImmutableDictionary with ImmutableInterlocked.AddOrUpdate shares structure instead.

5. Async reader/writer locks

The BCL has none. Options: the snapshot pattern (usually best), AsyncReaderWriterLock from Microsoft.VisualStudio.Threading, or AsyncReaderWriterLock in Nito.AsyncEx. They're more complex; prefer designs that don't need them.

6. Version notes

7. Try it yourself

1. Benchmark 8 threads doing lookups with lock, ReaderWriterLockSlim, a FrozenDictionary snapshot and ConcurrentDictionary.
2. Repeat with long read sections (simulate 10 µs of work) and see where RW starts to win.
3. Try upgrading a plain read lock with NoRecursion and observe the exception.
4. Run two upgradeable readers on separate threads and observe the second waiting.
5. Hold a write lock briefly every 100 ms during heavy long reads and measure reader tail latency.
6. Implement the snapshot Reload and confirm readers are never blocked during reloads.

using System.Collections.Frozen;
using System.Threading;

var rules = new RuleTable(new Dictionary<string, decimal> { ["AU"] = 0.10m });
Console.WriteLine(rules.TaxFor("AU"));
rules.Reload(new Dictionary<string, decimal> { ["AU"] = 0.10m, ["NZ"] = 0.15m });
Console.WriteLine(rules.TaxFor("NZ"));

var legacy = new LegacyRuleTable();
legacy.Set("AU", 0.10m);
Console.WriteLine(legacy.TryGet("AU", out var t) ? t : -1);

// Preferred: immutable snapshot, readers never block.
public sealed class RuleTable(IDictionary<string, decimal> initial)
{
    private FrozenDictionary<string, decimal> _rules = initial.ToFrozenDictionary();

    public decimal TaxFor(string country) =>
        Volatile.Read(ref _rules).TryGetValue(country, out var rate) ? rate : 0m;

    public void Reload(IDictionary<string, decimal> fresh) =>
        Volatile.Write(ref _rules, fresh.ToFrozenDictionary());
}

// ReaderWriterLockSlim version, for comparison.
public sealed class LegacyRuleTable : IDisposable
{
    private readonly ReaderWriterLockSlim _rw = new(LockRecursionPolicy.NoRecursion);
    private readonly Dictionary<string, decimal> _rules = new();

    public bool TryGet(string key, out decimal value)
    {
        _rw.EnterReadLock();
        try { return _rules.TryGetValue(key, out value); }
        finally { _rw.ExitReadLock(); }
    }

    public void Set(string key, decimal value)
    {
        _rw.EnterWriteLock();
        try { _rules[key] = value; }
        finally { _rw.ExitWriteLock(); }
    }

    public void Dispose() => _rw.Dispose();
}