Export (0) Print
Expand All
Expand Minimize
This topic has not yet been rated - Rate this topic

LazyThreadSafetyMode Enumeration

Specifies how a System.Lazy<T> instance synchronizes access among multiple threads.

Namespace:  System.Threading
Assembly:  mscorlib (in mscorlib.dll)
public enum LazyThreadSafetyMode
Member nameDescription
Supported by Portable Class LibrarySupported in .NET for Windows Store appsExecutionAndPublicationLocks are used to ensure that only a single thread can initialize a Lazy<T> instance in a thread-safe manner. If the initialization method (or the default constructor, if there is no initialization method) uses locks internally, deadlocks can occur. If you use a Lazy<T> constructor that specifies an initialization method (valueFactory parameter), and if that initialization method throws an exception (or fails to handle an exception) the first time you call the Lazy<T>.Value property, then the exception is cached and thrown again on subsequent calls to the Lazy<T>.Value property. If you use a Lazy<T> constructor that does not specify an initialization method, exceptions that are thrown by the default constructor for T are not cached. In that case, a subsequent call to the Lazy<T>.Value property might successfully initialize the Lazy<T> instance. If the initialization method recursively accesses the Value property of the Lazy<T> instance, an InvalidOperationException is thrown.
Supported by Portable Class LibrarySupported in .NET for Windows Store appsNoneThe Lazy<T> instance is not thread safe; if the instance is accessed from multiple threads, its behavior is undefined. Use this mode only when high performance is crucial and the Lazy<T> instance is guaranteed never to be initialized from more than one thread. If you use a Lazy<T> constructor that specifies an initialization method (valueFactory parameter), and if that initialization method throws an exception (or fails to handle an exception) the first time you call the Lazy<T>.Value property, then the exception is cached and thrown again on subsequent calls to the Lazy<T>.Value property. If you use a Lazy<T> constructor that does not specify an initialization method, exceptions that are thrown by the default constructor for T are not cached. In that case, a subsequent call to the Lazy<T>.Value property might successfully initialize the Lazy<T> instance. If the initialization method recursively accesses the Value property of the Lazy<T> instance, an InvalidOperationException is thrown.
Supported by Portable Class LibrarySupported in .NET for Windows Store appsPublicationOnlyWhen multiple threads try to initialize a Lazy<T> instance simultaneously, all threads are allowed to run the initialization method (or the default constructor, if there is no initialization method). The first thread to complete initialization sets the value of the Lazy<T> instance. That value is returned to any other threads that were simultaneously running the initialization method, unless the initialization method throws exceptions on those threads. Any instances of T that were created by the competing threads are discarded. If the initialization method throws an exception on any thread, the exception is propagated out of the Lazy<T>.Value property on that thread. The exception is not cached. The value of the IsValueCreated property remains false, and subsequent calls to the Value property, either by the thread where the exception was thrown or by other threads, cause the initialization method to run again. If the initialization method recursively accesses the Value property of the Lazy<T> instance, no exception is thrown.

Use this enumeration to specify the mode parameter of Lazy<T> constructors. The effects of all constructors on thread synchronization can be described in terms of this enumeration, whether or not they have mode parameters.

A Lazy<T> instance is initialized either by a user-specified initialization method or by the default constructor for T. The initialization method is specified by the valueFactory parameter of a Lazy<T> constructor. The method returns an instance of T, which is the type that is lazily instantiated by the instance of Lazy<T>. If a constructor does not have a valueFactory parameter, the default constructor for T is used to initialize the Lazy<T> instance. In either case, initialization occurs the first time you call the Lazy<T>.Value property.

In addition to specifying the thread safety of a Lazy<T> instance, this enumeration affects exception caching. When exceptions are cached for a Lazy<T> instance, you get only one chance to initialize the instance. If an exception is thrown the first time you call the Lazy<T>.Value property, that exception is cached and rethrown on all subsequent calls to the Lazy<T>.Value property. The advantage of caching exceptions is that any two threads always get the same result, even when errors occur.

When you specify the PublicationOnly mode, exceptions are never cached. When you specify None or ExecutionAndPublication, caching depends on whether you specify an initialization method or allow the default constructor for T to be used. Specifying an initialization method enables exception caching for these two modes. The initialization method can be very simple. For example, it might call the default constructor for T: new Lazy<Contents>(() => new Contents(), mode) in C#, or New Lazy(Of Contents)(Function() New Contents()) in Visual Basic. If you use a constructor that does not specify an initialization method, exceptions that are thrown by the default constructor for T are not cached. The following table summarizes exception caching behavior.

Mode

Using initialization method

Using default constructor for T

None

Cached

Not cached

PublicationOnly

Not cached

Not cached

ExecutionAndPublication

Cached

Not cached

.NET Framework

Supported in: 4.5.1, 4.5, 4

.NET Framework Client Profile

Supported in: 4

Portable Class Library

Supported in: Portable Class Library

.NET for Windows Store apps

Supported in: Windows 8

.NET for Windows Phone apps

Supported in: Windows Phone 8.1, Windows Phone 8, Silverlight 8.1

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.