Lazy Initialization
Updated: March 2011
Lazy initialization of an object means that its creation is deferred until it is first used. (For this topic, the terms lazy initialization and lazy instantiation are synonymous.) Lazy initialization is primarily used to improve performance, avoid wasteful computation, and reduce program memory requirements. These are the most common scenarios:
When you have an object that is expensive to create, and the program might not use it. For example, assume that you have in memory a Customer object that has an Orders property that contains a large array of Order objects that, to be initialized, requires a database connection. If the user never asks to display the Orders or use the data in a computation, then there is no reason to use system memory or computing cycles to create it. By using Lazy<Orders> to declare the Orders object for lazy initialization, you can avoid wasting system resources when the object is not used.
When you have an object that is expensive to create, and you want to defer its creation until after other expensive operations have been completed. For example, assume that your program loads several object instances when it starts, but only some of them are required immediately. You can improve the startup performance of the program by deferring initialization of the objects that are not required until the required objects have been created.
Although you can write your own code to perform lazy initialization, we recommend that you use Lazy<T> instead. Lazy<T> and its related types also support thread-safety and provide a consistent exception propagation policy.
The following table lists the types that the .NET Framework version 4 provides to enable lazy initialization in different scenarios.
Type |
Description |
|---|---|
A wrapper class that provides lazy initialization semantics for any class library or user-defined type. |
|
Resembles Lazy<T> except that it provides lazy initialization semantics on a thread-local basis. Every thread has access to its own unique value. |
|
Provides advanced static (Shared in Visual Basic) methods for lazy initialization of objects without the overhead of a class. |
Basic Lazy Initialization
To define a lazy-initialized type, for example, MyType, use Lazy<MyType> (Lazy(Of MyType) in Visual Basic), as shown in the following example. If no delegate is passed in the Lazy<T> constructor, the wrapped type is created by using Activator.CreateInstance when the value property is first accessed. If the type does not have a default constructor, a run-time exception is thrown.
In the following example, assume that Orders is a class that contains an array of Order objects retrieved from a database. A Customer object contains an instance of Orders, but depending on user actions, the data from the Orders object might not be required.
' Initialize by using default Lazy<T> constructor. The
'Orders array itself is not created yet.
Dim _orders As Lazy(Of Orders) = New Lazy(Of Orders)()
// Initialize by using default Lazy<T> constructor. The
// Orders array itself is not created yet.
Lazy<Orders> _orders = new Lazy<Orders>();
You can also pass a delegate in the Lazy<T> constructor that invokes a specific constructor overload on the wrapped type at creation time, and perform any other initialization steps that are required, as shown in the following example.
' Initialize by invoking a specific constructor on Order
' when Value property is accessed
Dim _orders As Lazy(Of Orders) = New Lazy(Of Orders)(Function() New Orders(100))
// Initialize by invoking a specific constructor on Order when Value
// property is accessed
Lazy<Orders> _orders = new Lazy<Orders>(() => new Orders(100));
After the Lazy object is created, no instance of Orders is created until the Value property of the Lazy variable is accessed for the first time. On first access, the wrapped type is created and returned, and stored for any future access.
' We need to create the array only if _displayOrders is true
If _displayOrders = True Then
DisplayOrders(_orders.Value.OrderData)
Else
' Don't waste resources getting order data.
End If
// We need to create the array only if displayOrders is true
if (displayOrders == true)
{
DisplayOrders(_orders.Value.OrderData);
}
else
{
// Don't waste resources getting order data.
}
A Lazy<T> object always returns the same object or value that it was initialized with. Therefore, the Value property is read-only. If Value stores a reference type, you cannot assign a new object to it. (However, you can change the value of its settable public fields and properties.) If Value stores a value type, you cannot modify its value. Nevertheless, you can create a new variable by invoking the variable constructor again by using new arguments.
_orders = New Lazy(Of Orders)(Function() New Orders(10))
_orders = new Lazy<Orders>(() => new Orders(10));
The new lazy instance, like the earlier one, does not instantiate Orders until its Value property is first accessed.
Thread-Safe Initialization
As stated earlier, a Lazy<T> object always returns the same object or value that it was initialized with, and therefore the Value property is read-only. If you enable exception caching, this immutability also extends to exception behavior. If a lazy-initialized object has exception caching enabled and throws an exception from its initialization method when the Value property is first accessed, that same exception is thrown on every subsequent attempt to access the Value property (or the ToString method). In other words, the constructor of the wrapped type is never re-invoked, even in multithreaded scenarios. Therefore, the Lazy<T> object cannot throw an exception on one access and return a value on a subsequent access.
Exception caching is enabled when you use any System.Lazy<T> constructor that takes an initialization method (valueFactory parameter); for example, it is enabled when you use the Lazy(T)(Func(T)) constructor. If the constructor also takes a LazyThreadSafetyMode value (mode parameter), specify LazyThreadSafetyMode.None or LazyThreadSafetyMode.ExecutionAndPublication. 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. For more information, see the LazyThreadSafetyMode enumeration.
.gif "Note") Note |
|---|
If you create a Lazy<T> object with the isThreadSafe constructor parameter set to false or the mode constructor parameter set to LazyThreadSafetyMode.None, you must access the Lazy<T> object from a single thread or provide your own synchronization. This applies to all aspects of the object, including exception caching. |
As noted in the previous section, Lazy<T> objects created by specifying LazyThreadSafetyMode.PublicationOnly treat exceptions differently. With PublicationOnly, multiple threads can compete to initialize the Lazy<T> instance. In this case, exceptions are not cached, and attempts to access the Value property can continue until initialization is successful.
The following table summarizes the way the Lazy<T> constructors control exception caching.
Constructor |
Thread safety mode |
Uses initialization method |
Exceptions are cached |
|---|---|---|---|
Lazy(T)() |
No |
No |
|
Lazy(T)(Func(T)) |
Yes |
Yes |
|
Lazy(T)(Boolean) |
True (ExecutionAndPublication) or false (None) |
No |
No |
Lazy(T)(Func(T), Boolean) |
True (ExecutionAndPublication) or false (None) |
Yes |
Yes |
Lazy(T)(LazyThreadSafetyMode) |
User-specified |
No |
No |
Lazy(T)(Func(T), LazyThreadSafetyMode) |
User-specified |
Yes |
No if user specifies PublicationOnly; otherwise, yes. |
Exceptions in Lazy Objects
As stated earlier, a Lazy<T> object always returns the same object or value that it was initialized with, and therefore, the Value property is read-only. For the most commonly used thread-safety modes, this immutability also extends to exception behavior. If a lazy-initialized object throws an exception from its initialization logic when the Value property is first accessed, that same exception is thrown on every subsequent attempt to access the Value property. In other words, the constructor of the wrapped type is never re-invoked, even in multi-threaded scenarios. Therefore, a lazy variable cannot throw an exception on one access and return a value on a subsequent access.
| Note |
|---|
If you create a Lazy<T> object that has the IsThreadSafe constructor argument set to false, and then access the object from multiple threads, one thread might raise an exception and another thread might see a usable value. Therefore, do not specify false for IsThreadSafe if there is any chance that multiple threads might try to access the lazy object simultaneously. |
As noted in the previous section, Lazy<T> objects created by specifying LazyThreadSafetyMode.PublicationOnly treat exceptions differently. With PublicationOnly, multiple threads can compete to initialize the Lazy<T> instance. In this case, exceptions are not cached, and attempts to access the Value property can continue until initialization is successful.
Implementing a Lazy-Initialized Property
To implement a public property by using lazy initialization, define the backing field of the property as a Lazy<T>, and return the Value property from the get accessor of the property.
Class Customer
Private _orders As Lazy(Of Orders)
Public Shared CustomerID As String
Public Sub New(ByVal id As String)
CustomerID = id
_orders = New Lazy(Of Orders)(Function()
' You can specify additional
' initialization steps here
Return New Orders(CustomerID)
End Function)
End Sub
Public ReadOnly Property MyOrders As Orders
Get
Return _orders.Value
End Get
End Property
End Class
class Customer
{
private Lazy<Orders> _orders;
public string CustomerID {get; private set;}
public Customer(string id)
{
CustomerID = id;
_orders = new Lazy<Orders>(() =>
{
// You can specify any additonal
// initialization steps here.
return new Orders(this.CustomerID);
});
}
public Orders MyOrders
{
get
{
// Orders is created on first access here.
return _orders.Value;
}
}
}
The Value property is read-only; therefore, the property that exposes it has no set accessor. If you require a read/write property backed by a Lazy<T> object, the set accessor must create a new Lazy<T> object and assign it to the backing store. The set accessor must create a lambda expression that returns the new property value that was passed to the set accessor, and pass that lambda expression to the constructor for the new Lazy<T> object. The next access of the Value property will cause initialization of the new Lazy<T>, and its Value property will thereafter return the new value that was assigned to the property. The reason for this convoluted arrangement is to preserve the multithreading protections built into Lazy<T>. Otherwise, the property accessors would have to cache the first value returned by the Value property and only modify the cached value, and you would have to write your own thread-safe code to do that. Because of the additional initializations required by a read/write property backed by a Lazy<T> object, the performance might not be acceptable. Furthermore, depending on the specific scenario, additional coordination might be required to avoid race conditions between setters and getters.
Thread-Local Lazy Initialization
In some multithreaded scenarios, you might want to give each thread its own private data. Such data is called thread-local data. In the .NET Framework version 3.5 and earlier, you could apply the ThreadStatic attribute to a static variable to make it thread-local. However, using the ThreadStatic attribute can lead to subtle errors. For example, even basic initialization statements will cause the variable to be initialized only on the first thread that accesses it, as shown in the following example.
<ThreadStatic()>
Shared counter As Integer
[ThreadStatic]
static int counter = 1;
On all other threads, the variable will be initialized by using its default value (zero). As an alternative in the .NET Framework version 4, you can use the System.Threading.ThreadLocal<T> type to create an instance-based, thread-local variable that is initialized on all threads by the Action<T> delegate that you provide. In the following example, all threads that access counter will see its starting value as 1.
Dim betterCounter As ThreadLocal(Of Integer) = New ThreadLocal(Of Integer)(Function() 1)
ThreadLocal<int> betterCounter = new ThreadLocal<int>(() => 1);
ThreadLocal<T> wraps its object in much the same way as Lazy<T>, with these essential differences:
Each thread initializes the thread-local variable by using its own private data that is not accessible from other threads.
The ThreadLocal<T>.Value property is read-write, and can be modified any number of times. This can affect exception propagation, for example, one get operation can raise an exception but the next one can successfully initialize the value.
If no initialization delegate is provided, ThreadLocal<T> will initialize its wrapped type by using the default value of the type. In this regard, ThreadLocal<T> is consistent with the ThreadStaticAttribute attribute.
The following example demonstrates that every thread that accesses the ThreadLocal<int> instance gets its own unique copy of the data.
' Initialize the integer to the managed thread id on a per-thread basis.
Dim threadLocalNumber As New ThreadLocal(Of Integer)(Function() Thread.CurrentThread.ManagedThreadId)
Dim t4 As New Thread(Sub()
Console.WriteLine("number on t4 = {0} threadID = {1}",
threadLocalNumber.Value, Thread.CurrentThread.ManagedThreadId)
End Sub)
t4.Start()
Dim t5 As New Thread(Sub()
Console.WriteLine("number on t5 = {0} threadID = {1}",
threadLocalNumber.Value, Thread.CurrentThread.ManagedThreadId)
End Sub)
t5.Start()
Dim t6 As New Thread(Sub()
Console.WriteLine("number on t6 = {0} threadID = {1}",
threadLocalNumber.Value, Thread.CurrentThread.ManagedThreadId)
End Sub)
t6.Start()
' Ensure that thread IDs are not recycled if the
' first thread completes before the last one starts.
t4.Join()
t5.Join()
t6.Join()
'Sample(Output)
' threadLocalNumber on t4 = 14 ThreadID = 14
' threadLocalNumber on t5 = 15 ThreadID = 15
' threadLocalNumber on t6 = 16 ThreadID = 16
// Initialize the integer to the managed thread id on a per-thread basis.
ThreadLocal<int> threadLocalNumber = new ThreadLocal<int>(() => Thread.CurrentThread.ManagedThreadId);
Thread t4 = new Thread(() => Console.WriteLine("threadLocalNumber on t4 = {0} ThreadID = {1}",
threadLocalNumber.Value, Thread.CurrentThread.ManagedThreadId));
t4.Start();
Thread t5 = new Thread(() => Console.WriteLine("threadLocalNumber on t5 = {0} ThreadID = {1}",
threadLocalNumber.Value, Thread.CurrentThread.ManagedThreadId));
t5.Start();
Thread t6 = new Thread(() => Console.WriteLine("threadLocalNumber on t6 = {0} ThreadID = {1}",
threadLocalNumber.Value, Thread.CurrentThread.ManagedThreadId));
t6.Start();
// Ensure that thread IDs are not recycled if the
// first thread completes before the last one starts.
t4.Join();
t5.Join();
t6.Join();
/* Sample Output:
threadLocalNumber on t4 = 14 ThreadID = 14
threadLocalNumber on t5 = 15 ThreadID = 15
threadLocalNumber on t6 = 16 ThreadID = 16
*/
Thread-Local Variables in Parallel.For and ForEach
When you use the Parallel.For method or Parallel.ForEach method to iterate over data sources in parallel, you can use the overloads that have built-in support for thread-local data. In these methods, the thread-locality is achieved by using local delegates to create, access, and clean up the data. For more information, see How to: Write a Parallel.For Loop That Has Thread-Local Variables and How to: Write a Parallel.ForEach Loop That Has Thread-Local Variables.
Using Lazy Initialization for Low-Overhead Scenarios
In scenarios where you have to lazy-initialize a large number of objects, you might decide that wrapping each object in a Lazy<T> requires too much memory or too many computing resources. Or, you might have stringent requirements about how lazy initialization is exposed. In such cases, you can use the static (Shared in Visual Basic) methods of the System.Threading.LazyInitializer class to lazy-initialize each object without wrapping it in an instance of Lazy<T>.
In the following example, assume that, instead of wrapping an entire Orders object in one Lazy<T> object, you have lazy-initialized individual Order objects only if they are required.
' Assume that _orders contains null values, and
' we only need to initialize them if displayOrderInfo is true
If displayOrderInfo = True Then
For i As Integer = 0 To _orders.Length
' Lazily initialize the orders without wrapping them in a Lazy(Of T)
LazyInitializer.EnsureInitialized(_orders(i), Function()
' Returns the value that will be placed in the ref parameter.
Return GetOrderForIndex(i)
End Function)
Next
End If
// Assume that _orders contains null values, and
// we only need to initialize them if displayOrderInfo is true
if(displayOrderInfo == true)
{
for (int i = 0; i < _orders.Length; i++)
{
// Lazily initialize the orders without wrapping them in a Lazy<T>
LazyInitializer.EnsureInitialized(ref _orders[i], () =>
{
// Returns the value that will be placed in the ref parameter.
return GetOrderForIndex(i);
});
}
}
In this example, notice that the initialization procedure is invoked on every iteration of the loop. In multi-threaded scenarios, the first thread to invoke the initialization procedure is the one whose value is seen by all threads. Later threads also invoke the initialization procedure, but their results are not used. If this kind of potential race condition is not acceptable, use the overload of LazyInitializer.EnsureInitialized that takes a Boolean argument and a synchronization object.
See Also
Tasks
How to: Perform Lazy Initialization of Objects
Concepts
Other Resources
Change History
Date |
History |
Reason |
|---|---|---|
|
March 2011 |
Corrected information about exception caching. |
Content bug fix. |