ReaderWriterLockSlim.EnterUpgradeableReadLock Method

Definition

Namespace:

System.Threading

Assemblies:

netstandard.dll, System.Threading.dll

Source:

ReaderWriterLockSlim.cs

Tries to enter the lock in upgradeable mode.

C#

public void EnterUpgradeableReadLock();

Exceptions

LockRecursionException

The RecursionPolicy property is NoRecursion and the current thread has already entered the lock in any mode.

-or-

The current thread has entered read mode, so trying to enter upgradeable mode would create the possibility of a deadlock.

-or-

The recursion number would exceed the capacity of the counter. The limit is so large that applications should never encounter it.

ObjectDisposedException

The ReaderWriterLockSlim object has been disposed.

Examples

The following example shows how to use the EnterUpgradeableReadLock method to enter the lock in upgradeable mode. A finally block is used to execute the ExitUpgradeableReadLock method, ensuring that the caller exits upgradeable mode.

The method shown in the example retrieves the value associated with a key and compares it with a new value. If the value is unchanged, the method returns a status indicating no change. If no value is found for the key, the key/value pair is inserted. If the value has changed, it is updated. Upgradeable mode allows the thread to upgrade the read lock as needed, without risk of deadlocks.

The example uses the parameterless constructor to create the lock, so recursion is not allowed. Programming the ReaderWriterLockSlim is simpler and less prone to error when the lock does not allow recursion.

This code is part of a larger example provided for the ReaderWriterLockSlim class.

C#

private ReaderWriterLockSlim cacheLock = new ReaderWriterLockSlim();
private Dictionary<int, string> innerCache = new Dictionary<int, string>();

C#

public AddOrUpdateStatus AddOrUpdate(int key, string value)
{
    cacheLock.EnterUpgradeableReadLock();
    try
    {
        string result = null;
        if (innerCache.TryGetValue(key, out result))
        {
            if (result == value)
            {
                return AddOrUpdateStatus.Unchanged;
            }
            else
            {
                cacheLock.EnterWriteLock();
                try
                {
                    innerCache[key] = value;
                }
                finally
                {
                    cacheLock.ExitWriteLock();
                }
                return AddOrUpdateStatus.Updated;
            }
        }
        else
        {
            cacheLock.EnterWriteLock();
            try
            {
                innerCache.Add(key, value);
            }
            finally
            {
                cacheLock.ExitWriteLock();
            }
            return AddOrUpdateStatus.Added;
        }
    }
    finally
    {
        cacheLock.ExitUpgradeableReadLock();
    }
}

C#

public enum AddOrUpdateStatus
{
    Added,
    Updated,
    Unchanged
};

Remarks

This method blocks until the calling thread enters the lock, and therefore might never return. Use the TryEnterUpgradeableReadLock method to block for a specified interval, and then return if the calling thread has not entered upgradeable mode during that interval.

Use upgradeable mode when a thread usually accesses the resource that is protected by the ReaderWriterLockSlim in read mode, but may need to enter write mode if certain conditions are met. A thread in upgradeable mode can downgrade to read mode or upgrade to write mode.

Only one thread can enter upgradeable mode at any given time. If a thread is in upgradeable mode, and there are no threads waiting to enter write mode, any number of other threads can enter read mode, even if there are threads waiting to enter upgradeable mode.

If one or more threads are waiting to enter write mode, a thread that calls the EnterUpgradeableReadLock method blocks until those threads have either timed out or entered write mode and then exited from it.

Note

If a lock allows recursion, a thread that has entered the lock in upgradeable mode can enter upgradeable mode recursively, even if other threads are waiting to enter write mode.

Applies to