ReaderWriterLockSlim.EnterUpgradeableReadLock Method

Definition

Namespace:

System.Threading

Assembly:

System.Threading.dll

Source:

ReaderWriterLockSlim.cs

Tries to enter the lock in upgradeable mode.

public:
 void EnterUpgradeableReadLock();

public void EnterUpgradeableReadLock ();

member this.EnterUpgradeableReadLock : unit -> unit

Public Sub 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.

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

Private cacheLock As New ReaderWriterLockSlim()
Private innerCache As New Dictionary(Of Integer, String)

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();
    }
}

Public Function AddOrUpdate(ByVal key As Integer, _
                            ByVal value As String) As AddOrUpdateStatus
    cacheLock.EnterUpgradeableReadLock()
    Try
        Dim result As String = Nothing
        If innerCache.TryGetValue(key, result) Then
            If result = value Then
                Return AddOrUpdateStatus.Unchanged
            Else
                cacheLock.EnterWriteLock()
                Try
                    innerCache.Item(key) = value
                Finally
                    cacheLock.ExitWriteLock()
                End Try
                Return AddOrUpdateStatus.Updated
            End If
        Else
            cacheLock.EnterWriteLock()
            Try
                innerCache.Add(key, value)
            Finally
                cacheLock.ExitWriteLock()
            End Try
            Return AddOrUpdateStatus.Added
        End If
    Finally
        cacheLock.ExitUpgradeableReadLock()
    End Try
End Function

public enum AddOrUpdateStatus
{
    Added,
    Updated,
    Unchanged
};

Public Enum AddOrUpdateStatus
    Added
    Updated
    Unchanged
End Enum

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.