System.Core 4.0.0.0 System.Object System.IDisposable Use to protect a resource that is read by multiple threads and written to by one thread at a time. allows multiple threads to be in read mode, allows one thread to be in write mode with exclusive ownership of the lock, and allows one thread that has read access to be in upgradeable read mode, from which the thread can upgrade to write mode without having to relinquish its read access to the resource. is similar to , but it has simplified rules for recursion and for upgrading and downgrading lock state. avoids many cases of potential deadlock. In addition, the performance of is significantly better than . is recommended for all new development. By default, new instances of are created with the flag and do not allow recursion. This default policy is recommended for all new development, because recursion introduces unnecessary complications and makes your code more prone to deadlocks. To simplify migration from existing projects that use or , you can use the flag to create instances of that allow recursion. A thread can enter the lock in three modes: read mode, write mode, and upgradeable read mode. (In the rest of this topic, "upgradeable read mode" is referred to as "upgradeable mode", and the phrase "enter mode" is used in preference to the longer phrase "enter the lock in mode".) Regardless of recursion policy, only one thread can be in write mode at any time. When a thread is in write mode, no other thread can enter the lock in any mode. Only one thread can be in upgradeable mode at any time. Any number of threads can be in read mode, and there can be one thread in upgradeable mode while other threads are in read mode. has managed thread affinity; that is, each object must make its own method calls to enter and exit lock modes. No thread can change the mode of another thread. If a does not allow recursion, a thread that tries to enter the lock can block for several reasons: A thread that tries to enter read mode blocks if there are threads waiting to enter write mode or if there is a single thread in write mode. Blocking new readers when writers are queued is a lock fairness policy that favors writers. The current fairness policy balances fairness to readers and writers, to promote throughput in the most common scenarios. Future versions of the dnprdnshort may introduce new fairness policies. A thread that tries to enter upgradeable mode blocks if there is already a thread in upgradeable mode, if there are threads waiting to enter write mode, or if there is a single thread in write mode. A thread that tries to enter write mode blocks if there is a thread in any of the three modes.

Upgrading and Downgrading Locks

Upgradeable mode is intended for cases where a thread usually reads from the protected resource, but might need to write to it if some condition is met. A thread that has entered a in upgradeable mode has read access to the protected resource, and can upgrade to write mode by calling the or methods. Because there can be only one thread in upgradeable mode at a time, upgrading to write mode cannot deadlock when recursion is not allowed, which is the default policy. Regardless of recursion policy, a thread that initially entered read mode is not allowed to upgrade to upgradeable mode or write mode, because that pattern creates a strong probability of deadlocks. For example, if two threads in read mode both try to enter write mode, they will deadlock. Upgradeable mode is designed to avoid such deadlocks. If there are other threads in read mode, the thread that is upgrading blocks. While the thread is blocked, other threads that try to enter read mode are blocked. When all threads have exited from read mode, the blocked upgradeable thread enters write mode. If there are other threads waiting to enter write mode, they remain blocked, because the single thread that is in upgradeable mode prevents them from gaining exclusive access to the resource. When the thread in upgradeable mode exits write mode, other threads that are waiting to enter read mode can do so, unless there are threads waiting to enter write mode. The thread in upgradeable mode can upgrade and downgrade indefinitely, as long as it is the only thread that writes to the protected resource. If you allow multiple threads to enter write mode or upgradeable mode, you must not allow one thread to monopolize upgradeable mode. Otherwise, threads that try to enter write mode directly will be blocked indefinitely, and while they are blocked, other threads will be unable to enter read mode. A thread in upgradeable mode can downgrade to read mode by first calling the method and then calling the method. This downgrade pattern is allowed for all lock recursion policies, even . After downgrading to read mode, a thread cannot reenter upgradeable mode until it has exited from read mode.

Entering the Lock Recursively

You can create a that supports recursive lock entry by using the constructor that specifies lock policy, and specifying . The use of recursion is not recommended for new development, because it introduces unnecessary complications and makes your code more prone to deadlocks. For a that allows recursion, the following can be said about the modes a thread can enter: A thread in read mode can enter read mode recursively, but cannot enter write mode or upgradeable mode. If it tries to do this, a is thrown. Entering read mode and then entering write mode or upgradeable mode is a pattern with a strong probability of deadlocks, so it is not allowed. As discussed earlier, upgradeable mode is provided for cases where it is necessary to upgrade a lock. A thread in upgradeable mode can enter write mode and/or read mode, and can enter any of the three modes recursively. However, an attempt to enter write mode blocks if there are other threads in read mode. A thread in write mode can enter read mode and/or upgradeable mode, and can enter any of the three modes recursively. A thread that has not entered the lock can enter any mode. This attempt can block for the same reasons as an attempt to enter a non-recursive lock. A thread can exit the modes it has entered in any order, as long as it exits each mode exactly as many times as it entered that mode. If a thread tries to exit a mode too many times, or to exit a mode it has not entered, a is thrown.

Lock States

You may find it useful to think of the lock in terms of its states. A can be in one of four states: not entered, read, upgrade, and write. Not entered: In this state, no threads have entered the lock (or all threads have exited the lock). Read: In this state, one or more threads have entered the lock for read access to the protected resource. A thread can enter the lock in read mode by using the or methods, or by downgrading from upgradeable mode. Upgrade: In this state, one thread has entered the lock for read access with the option to upgrade to write access (that is, in upgradeable mode), and zero or more threads have entered the lock for read access. No more than one thread at a time can enter the lock with the option to upgrade; additional threads that try to enter upgradeable mode are blocked. Write: In this state, one thread has entered the lock for write access to the protected resource. That thread has exclusive possession of the lock. Any other thread that tries to enter the lock for any reason is blocked. The following table describes the transitions between lock states, for locks that do not allow recursion, when a thread takes the action described in the leftmost column. At the time it takes the action, has no mode. (The special case where is in upgradeable mode is described in the table footnotes.) The top row describes the starting state of the lock. The cells describe what happens to the thread, and show changes to the lock state in parentheses. Not entered (N) Read (R) Upgrade (U) Write (W) enters read mode enters (R). blocks if threads are waiting for write mode; otherwise, enters. blocks if threads are waiting for write mode; otherwise, enters.1 blocks. enters upgradeable mode enters (U). blocks if threads are waiting for write mode or upgrade mode; otherwise, enters (U). blocks. blocks. enters write mode enters (W). blocks. blocks.2 blocks. 1 If starts out in upgradeable mode, it enters read mode. This action never blocks. The lock state does not change. (The thread can then complete a downgrade to read mode by exiting upgradeable mode.) 2 If starts out in upgradeable mode, it blocks if there are threads in read mode. Otherwise it upgrades to write mode. The lock state changes to Write (W). If blocks because there are threads in read mode, it enters write mode as soon as the last thread exits read mode, even if there are threads waiting to enter write mode. When a state change occurs because a thread exits the lock, the next thread to be awakened is selected as follows: First, a thread that is waiting for write mode and is already in upgradeable mode (there can be at most one such thread). Failing that, a thread that is waiting for write mode. Failing that, a thread that is waiting for upgradeable mode. Failing that, all threads that are waiting for read mode. The subsequent state of the lock is always Write (W) in the first two cases and Upgrade (U) in the third case, regardless of the state of the lock when the exiting thread triggered the state change. In the last case, the state of the lock is Upgrade (U) if there is a thread in upgradeable mode after the state change, and Read (R) otherwise, regardless of the prior state.

Represents a lock that is used to manage access to a resource, allowing multiple threads for reading or exclusive access for writing.

Constructor 4.0.0.0 A that is initialized with this constructor does not allow recursion. That is, the property returns . For more information about recursion policy and its effects, see the enumeration and the class.

Initializes a new instance of the class with default property values.

Constructor 4.0.0.0 Recursion policy determines the restrictions on threads that enter the lock more than once. For example, if a lock was created with and a thread has entered the lock in read mode, is thrown if the thread tries to reenter the lock in read mode. Similarly, if a thread has entered the lock in write mode, is thrown if the thread tries to reenter the lock in any mode. A thread in upgradeable mode can upgrade to write mode or downgrade to read mode regardless of the lock recursion policy setting. Regardless of recursion policy, a thread that initially entered read mode is not allowed to upgrade to upgradeable mode or write mode, because that pattern creates a strong probability of deadlocks. For more information about recursion policy and its effects, see the enumeration and the class.

Initializes a new instance of the class, specifying the lock recursion policy.

One of the enumeration values that specifies the lock recursion policy. Property 4.0.0.0 System.Int32 To be added. A thread is counted only once, even if the lock allows recursion and the thread has entered read mode multiple times. Use this property only for debugging, profiling, and logging purposes, and not to control the behavior of an algorithm. The results can change as soon as they have been calculated. Therefore, it is not safe to make decisions based on this property.

Gets the total number of unique threads that have entered the lock in read mode.

Method 4.0.0.0 System.Void Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see Cleaning Up Unmanaged Resources and Implementing a Dispose Method. Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's Finalize method.

Releases all resources used by the current instance of the class.

Method 4.0.0.0 System.Void This method blocks until the calling thread enters the lock, and therefore might never return. Use the method to block for a specified interval, and then return if the calling thread has not entered read mode during that interval. Multiple threads can enter read mode at the same time. If one or more threads are waiting to enter write mode, a thread that calls the method blocks until those threads have either timed out or entered write mode and then exited from it. If a lock allows recursion, a thread that has entered the lock in read mode can enter read mode recursively, even if other threads are waiting to enter write mode. At most one thread can be in upgradeable mode while other threads are in read mode. If additional threads are waiting to enter upgradeable mode, and there are no threads waiting to enter write mode, threads that call the method enter read mode immediately and do not block.

Tries to enter the lock in read mode.

Method 4.0.0.0 System.Void This method blocks until the calling thread enters the lock, and therefore might never return. Use the 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 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 method blocks until those threads have either timed out or entered write mode and then exited from it. 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.

Tries to enter the lock in upgradeable mode.

Method 4.0.0.0 System.Void This method blocks until the calling thread enters the lock, and therefore might never return. Use the method to block for a specified interval, and then return if the calling thread has not entered write mode during that interval. If other threads have entered the lock in read mode, a thread that calls the method blocks until those threads have exited read mode. When there are threads waiting to enter write mode, additional threads that try to enter read mode or upgradeable mode block until all the threads waiting to enter write mode have either timed out or entered write mode and then exited from it. If a lock allows recursion, a thread that has entered the lock in write mode can enter write mode recursively, even if other threads are waiting to enter write mode.

Tries to enter the lock in write mode.

Method 4.0.0.0 System.Void This method is not sensitive to recursion order. For example, if a thread enters a lock in upgradeable mode and then enters the lock in read mode, the order in which the thread exits the two modes does not matter. If a lock allows recursion, a thread can enter the lock in write mode and then enter it recursively in read mode; the order in which the thread exits read mode and write mode does not matter. Exiting the lock might signal other waiting threads.

Reduces the recursion count for read mode, and exits read mode if the resulting count is 0 (zero).

Method 4.0.0.0 System.Void This method is not sensitive to recursion order. For example, if a thread enters a lock in upgradeable mode and then enters the lock in write mode, the order in which the thread exits the two modes does not matter. If a lock allows recursion, a thread can enter the lock in write mode and then enter it recursively in upgradeable mode; the order in which the thread exits upgradeable mode and write mode does not matter. Exiting the lock might signal other waiting threads.

Reduces the recursion count for upgradeable mode, and exits upgradeable mode if the resulting count is 0 (zero).

Method 4.0.0.0 System.Void This method is not sensitive to recursion order. For example, if a thread enters a lock in upgradeable mode and then enters the lock in write mode, the order in which the thread exits the two modes does not matter. If a lock allows recursion, a thread can enter the lock in write mode and then enter it recursively in read mode; the order in which the thread exits read mode and write mode does not matter. Exiting the lock might signal other waiting threads.

Reduces the recursion count for write mode, and exits write mode if the resulting count is 0 (zero).

Property 4.0.0.0 System.Boolean To be added. This property is intended for use in asserts or for other debugging purposes. Do not use it to control the flow of program execution.

Gets a value that indicates whether the current thread has entered the lock in read mode.

Property 4.0.0.0 System.Boolean To be added. This property is intended for use in asserts or for other debugging purposes. Do not use it to control the flow of program execution.

Gets a value that indicates whether the current thread has entered the lock in upgradeable mode.

Property 4.0.0.0 System.Boolean To be added. This property is intended for use in asserts or for other debugging purposes. Do not use it to control the flow of program execution.

Gets a value that indicates whether the current thread has entered the lock in write mode.

Property 4.0.0.0 System.Threading.LockRecursionPolicy To be added. Recursion policy determines the restrictions on threads that enter the lock more than once. For example, if a lock was created with and a thread has entered the lock in read mode, is thrown if the thread tries to reenter the lock in read mode. A thread in upgradeable mode can upgrade to write mode or downgrade to read mode regardless of the lock recursion policy setting. Regardless of recursion policy, a thread that initially entered read mode is not allowed to upgrade to upgradeable mode or write mode, because that pattern creates a strong probability of deadlocks. For more information about recursion policy and its effects, see the enumeration and the class.

Gets a value that indicates the recursion policy for the current object.

Property 4.0.0.0 System.Int32 To be added. Use this property only for debugging, profiling, and logging purposes, and not to control the behavior of an algorithm. The results can change as soon as they have been calculated. Therefore, it is not safe to make decisions based on this property.

Gets the number of times the current thread has entered the lock in read mode, as an indication of recursion.

Gets the number of times the current thread has entered the lock in upgradeable mode, as an indication of recursion.

Gets the number of times the current thread has entered the lock in write mode, as an indication of recursion.

Method 4.0.0.0 System.Boolean If is 0 (zero), this method checks the lock state and returns false immediately if the desired state is unavailable. Multiple threads can enter read mode at the same time. If one or more threads are waiting to enter write mode, a thread that calls the method blocks until those threads have either timed out or entered write mode and then exited from it, or until the calling thread's own time-out interval expires. If a lock allows recursion, a thread that has entered the lock in read mode can enter read mode recursively, even if other threads are waiting to enter write mode. One thread can be in upgradeable mode while other threads are in read mode. If additional threads are waiting to enter upgradeable mode, and there are no threads waiting to enter write mode, threads that call the method enter read mode immediately and do not block.

Tries to enter the lock in read mode, with an optional integer time-out.

true if the calling thread entered read mode, otherwise, false. The number of milliseconds to wait, or -1 () to wait indefinitely. Method 4.0.0.0 System.Boolean If is 0 (zero), this method checks the lock state and returns false immediately if the desired state is unavailable. Multiple threads can enter the lock in read mode at the same time. If one or more threads are queued to enter write mode, a thread that calls the method blocks until those threads have either timed out or entered write mode and then exited from it, or until the calling thread's own time-out interval expires. If a lock allows recursion, a thread that has entered the lock in read mode can enter read mode recursively, even if other threads are waiting to enter write mode. One thread can be in upgradeable mode while other threads are in read mode. If additional threads are waiting to enter upgradeable mode, and there are no threads waiting to enter write mode, threads that call the method enter read mode immediately and do not block.

Tries to enter the lock in read mode, with an optional time-out.

true if the calling thread entered read mode, otherwise, false. The interval to wait, or -1 milliseconds to wait indefinitely. Method 4.0.0.0 System.Boolean If is 0 (zero), this method checks the lock state and returns false immediately if the desired state is unavailable. Use upgradeable mode when a thread usually accesses the resource that is protected by the in read mode, but may need to enter write mode if certain conditions are met. A thread in upgradeable mode can upgrade to write mode or downgrade to read mode. Only one thread can enter a lock in 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 method blocks until those threads have either timed out or entered write mode and then exited from it, or until the calling thread's own time-out interval expires. 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.

Tries to enter the lock in upgradeable mode, with an optional time-out.

true if the calling thread entered upgradeable mode, otherwise, false. The number of milliseconds to wait, or -1 () to wait indefinitely. Method 4.0.0.0 System.Boolean If is 0 (zero), this method checks the lock state and returns false immediately if the desired state is unavailable. Use upgradeable mode when a thread usually accesses the resource protected by the in read mode, but may need to enter write mode if certain conditions are met. A thread in upgradeable mode can upgrade to write mode or downgrade to read mode. Only one thread can enter a lock in 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 method blocks until those threads have either timed out or entered write mode and then exited from it, or until the calling thread's own time-out interval expires. 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.

Tries to enter the lock in upgradeable mode, with an optional time-out.

true if the calling thread entered upgradeable mode, otherwise, false. The interval to wait, or -1 milliseconds to wait indefinitely. Method 4.0.0.0 System.Boolean If is 0 (zero), this method checks the lock state and returns false immediately if the desired state is unavailable. If other threads have entered the lock in read mode, a thread that calls the method blocks until those threads have exited read mode or until the time-out interval has elapsed. While threads are blocked waiting to enter write mode, additional threads that try to enter read mode or upgradeable mode block until all the threads waiting to enter write mode have either timed out or entered write mode and then exited from it. If a lock allows recursion, a thread that has entered the lock in write mode can enter write mode recursively, even if other threads are waiting to enter write mode.

Tries to enter the lock in write mode, with an optional time-out.

true if the calling thread entered write mode, otherwise, false. The number of milliseconds to wait, or -1 () to wait indefinitely. Method 4.0.0.0 System.Boolean If is 0 (zero), this method checks the lock state and returns false immediately if the desired state is unavailable. If other threads have entered the lock in read mode, a thread that calls the method blocks until those threads have exited read mode or until the time-out interval has elapsed. While threads are blocked waiting to enter write mode, additional threads that try to enter read mode or upgradeable mode block until all the threads waiting to enter write mode have either timed out or entered write mode and then exited from it. If a lock allows recursion, a thread that has entered the lock in write mode can enter write mode recursively, even if other threads are waiting to enter write mode.

Tries to enter the lock in write mode, with an optional time-out.

true if the calling thread entered write mode, otherwise, false. The interval to wait, or -1 milliseconds to wait indefinitely. Property 4.0.0.0 System.Int32 To be added. Use this property only for debugging, profiling, and logging purposes, and not to control the behavior of an algorithm. The results can change as soon as they have been calculated. Therefore, it is not safe to make decisions based on this property.

Gets the total number of threads that are waiting to enter the lock in read mode.

Gets the total number of threads that are waiting to enter the lock in upgradeable mode.

Gets the total number of threads that are waiting to enter the lock in write mode.