{"id":20679,"date":"2018-11-07T10:00:31","date_gmt":"2018-11-07T17:00:31","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/dotnet\/?p=20085"},"modified":"2025-03-15T16:03:24","modified_gmt":"2025-03-15T23:03:24","slug":"understanding-the-whys-whats-and-whens-of-valuetask","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/understanding-the-whys-whats-and-whens-of-valuetask\/","title":{"rendered":"Understanding the Whys, Whats, and Whens of ValueTask"},"content":{"rendered":"

The .NET Framework 4 saw the introduction of the\u00a0System.Threading.Tasks<\/code>\u00a0namespace, and with it the\u00a0Task<\/code>\u00a0class. This type and the derived\u00a0Task<TResult><\/code>\u00a0have long since become a staple of .NET programming, key aspects of the asynchronous programming model introduced with C# 5 and its\u00a0async<\/code>\u00a0\/\u00a0await<\/code>\u00a0keywords. In this post, I’ll cover the newer\u00a0ValueTask<\/code>\/ValueTask<TResult><\/code>\u00a0types, which were introduced to help improve asynchronous performance in common use cases where decreased allocation overhead is important.<\/p>\n

Task<\/h2>\n

Task<\/code>\u00a0serves multiple purposes, but at its core it’s a “promise”, an object that represents the eventual completion of some operation. You initiate an operation and get back a\u00a0Task<\/code>\u00a0for it, and that\u00a0Task<\/code>\u00a0will complete when the operation completes, which may happen synchronously as part of initiating the operation (e.g. accessing some data that was already buffered), asynchronously but complete by the time you get back the\u00a0Task<\/code>\u00a0(e.g. accessing some data that wasn’t yet buffered but that was very fast to access), or asynchronously and complete after you’re already holding the\u00a0Task<\/code>\u00a0(e.g. accessing some data from across a network). Since operations might complete asynchronously, you either need to block waiting for the results (which often defeats the purpose of the operation having been asynchronous to begin with) or you need to supply a callback that’ll be invoked when the operation completes. In .NET 4, providing such a callback was achieved via\u00a0ContinueWith<\/code>\u00a0methods on the\u00a0Task<\/code>, which explicitly exposed the callback model by accepting a delegate to invoke when the\u00a0Task<\/code>\u00a0completed:<\/p>\n

\n
SomeOperationAsync().ContinueWith(task =>\r\n{\r\n    try\r\n    {\r\n        TResult result = task.Result;\r\n        UseResult(result);\r\n    }\r\n    catch (Exception e)\r\n    {\r\n        HandleException(e);\r\n    }\r\n});<\/pre>\n<\/div>\n
But with the .NET Framework 4.5 and C# 5,\u00a0Task<\/code>s could simply be\u00a0await<\/code>ed, making it easy to consume the results of an asynchronous operation, and with the generated code being able to optimize all of the aforementioned cases, correctly handling things regardless of whether the operation completes synchronously, completes asynchronously quickly, or completes asynchronously after already (implicitly) providing a callback:<\/p>\n
\n
TResult result = await SomeOperationAsync();\r\nUseResult(result);<\/pre>\n<\/div>\n
Task<\/code>\u00a0as a class is very flexible and has resulting benefits. For example, you can await it multiple times, by any number of consumers concurrently. You can store one into a dictionary for any number of subsequent consumers to await in the future, which allows it to be used as a cache for asynchronous results. You can block waiting for one to complete should the scenario require that. And you can write and consume a large variety of operations over tasks (sometimes referred to as “combinators”), such as a “when any” operation that asynchronously waits for the first to complete.<\/p>\n
However, that flexibility is not needed for the most common case: simply invoking an asynchronous operation and awaiting its resulting task:<\/p>\n
\n
TResult result = await SomeOperationAsync();\r\nUseResult(result);<\/pre>\n<\/div>\n
In such usage, we don’t need to be able to await the task multiple times. We don’t need to be able to handle concurrent awaits. We don’t need to be able to handle synchronous blocking. We don’t need to write combinators. We simply need to be able to await the resulting promise of the asynchronous operation. This is, after all, how we write synchronous code (e.g.\u00a0TResult result = SomeOperation();<\/code>), and it naturally translates to the world of\u00a0async<\/code>\u00a0\/\u00a0await<\/code>.<\/p>\n
Further,\u00a0Task<\/code>\u00a0does have a potential downside, in particular for scenarios where instances are created\u00a0a lot<\/em>\u00a0and where high-throughput and performance is a key concern:\u00a0Task<\/code>\u00a0is a class. As a class, that means that any operation which needs to create one needs to allocate an object, and the more objects that are allocated, the more work the garbage collector (GC) needs to do, and the more resources we spend on it that could be spent doing other things.<\/p>\n
The runtime and core libraries mitigate this in many situations. For example, if you write a method like the following:<\/p>\n
\n
public async Task WriteAsync(byte value)\r\n{\r\n    if (_bufferedCount == _buffer.Length)\r\n    {\r\n        await FlushAsync();\r\n    }\r\n    _buffer[_bufferedCount++] = value;\r\n}<\/pre>\n<\/div>\n
in the common case there will be space available in the buffer and the operation will complete synchronously. When it does, there’s nothing special about the\u00a0Task<\/code>\u00a0that needs to be returned, since there’s no return value: this is the\u00a0Task<\/code>-based equivalent of a\u00a0void<\/code>-returning synchronous method. Thus, the runtime can simply cache a single non-generic\u00a0Task<\/code>\u00a0and use that over and over again as the result task for any\u00a0async Task<\/code>\u00a0method that completes synchronously (that cached singleton is exposed via `Task.CompletedTask`). Or for example, if you write:<\/p>\n
\n
public async Task<bool> MoveNextAsync()\r\n{\r\n    if (_bufferedCount == 0)\r\n    {\r\n        await FillBuffer();\r\n    }\r\n    return _bufferedCount > 0;\r\n}<\/pre>\n<\/div>\n
in the common case, we expect there to be some data buffered, in which case this method simply checks\u00a0_bufferedCount<\/code>, sees that it’s larger than\u00a00<\/code>, and returns\u00a0true<\/code>; only if there’s currently no buffered data does it need to perform an operation that might complete asynchronously. And since there are only two possible\u00a0Boolean<\/code>\u00a0results (true<\/code>\u00a0and\u00a0false<\/code>), there are only two possible\u00a0Task<bool><\/code>\u00a0objects needed to represent all possible result values, and so the runtime is able to cache two such objects and simply return a cached\u00a0Task<bool><\/code>\u00a0with a\u00a0Result<\/code>\u00a0of\u00a0true<\/code>, avoiding the need to allocate. Only if the operation completes asynchronously does the method then need to allocate a new\u00a0Task<bool><\/code>, because it needs to hand back the object to the caller before it knows what the result of the operation will be, and needs to have a unique object into which it can store the result when the operation does complete.<\/p>\n
The runtime maintains a small such cache for other types as well, but it’s not feasible to cache everything. For example, a method like:<\/p>\n
\n
public async Task<int> ReadNextByteAsync()\r\n{\r\n    if (_bufferedCount == 0)\r\n    {\r\n        await FillBuffer();\r\n    }\r\n\r\n    if (_bufferedCount == 0)\r\n    {\r\n        return -1;\r\n    }\r\n\r\n    _bufferedCount--;\r\n    return _buffer[_position++];\r\n}<\/pre>\n<\/div>\n
will also frequently complete synchronously. But unlike the\u00a0Boolean<\/code>\u00a0case, this method returns an\u00a0Int32<\/code>\u00a0value, which has ~4 billion possible results, and caching a\u00a0Task<int><\/code>\u00a0for all such cases would consume potentially hundreds of gigabytes of memory. The runtime does maintain a small cache for\u00a0Task<int><\/code>, but only for a few small result values, so for example if this completes synchronously (there’s data in the buffer) with a value like 4, it’ll end up using a cached task, but if it completes synchronously with a value like 42, it’ll end up allocating a new\u00a0Task<int><\/code>, akin to calling\u00a0Task.FromResult(42)<\/code>.<\/p>\n
Many library implementations attempt to mitigate this further by maintaining their own cache as well. For example, the\u00a0MemoryStream.ReadAsync<\/code>\u00a0overload introduced in the .NET Framework 4.5 always completes synchronously, since it’s just reading data from memory.\u00a0ReadAsync<\/code>\u00a0returns a\u00a0Task<int><\/code>, where the\u00a0Int32<\/code>\u00a0result represents the number of bytes read.\u00a0ReadAsync<\/code>\u00a0is often used in a loop, often with the number of bytes requested the same on each call, and often with\u00a0ReadAsync<\/code>\u00a0able to fully fulfill that request. Thus, it’s common for repeated calls to\u00a0ReadAsync<\/code>\u00a0to return a\u00a0Task<int><\/code>\u00a0synchronously with the same result as it did on the previous call. As such,\u00a0MemoryStream<\/code>\u00a0maintains a cache of a single task, the last one it returned successfully. Then on a subsequent call, if the new result matches that of its cached\u00a0Task<int><\/code>, it just returns the cached one again; otherwise, it uses\u00a0Task.FromResult<\/code>\u00a0to create a new one, stores that as its new cached task, and returns it.<\/p>\n
Even so, there are many cases where operations complete synchronously and are forced to allocate a\u00a0Task<TResult><\/code>\u00a0to hand back.<\/a><\/p>\n
ValueTask <TResult> and synchronous completion<\/h2>\n
All of this motivated the introduction of a new type in .NET Core 2.0 and made available for previous .NET releases via a\u00a0System.Threading.Tasks.Extensions<\/code>\u00a0NuGet package:\u00a0ValueTask<TResult><\/code>.<\/p>\n
ValueTask<TResult><\/code>\u00a0was introduced in .NET Core 2.0 as a struct capable of wrapping either a\u00a0TResult<\/code>\u00a0or a\u00a0Task<TResult><\/code>. This means it can be returned from an async method, and if that method completes synchronously and successfully, nothing need be allocated: we can simply initialize this\u00a0ValueTask<TResult><\/code>\u00a0struct with the\u00a0TResult<\/code>\u00a0and return that. Only if the method completes asynchronously does a\u00a0Task<TResult><\/code>\u00a0need to be allocated, with the\u00a0ValueTask<TResult><\/code>\u00a0created to wrap that instance (to minimize the size of\u00a0ValueTask<TResult><\/code>\u00a0and to optimize for the success path, an async method that faults with an unhandled exception will also allocate a\u00a0Task<TResult><\/code>, so that the\u00a0ValueTask<TResult><\/code>\u00a0can simply wrap that\u00a0Task<TResult><\/code>\u00a0rather than always having to carry around an additional field to store an\u00a0Exception<\/code>).<\/p>\n
With that, a method like\u00a0MemoryStream.ReadAsync<\/code>\u00a0that instead returns a\u00a0ValueTask<int><\/code>\u00a0need not be concerned with caching, and can instead be written with code like:<\/p>\n
\n
public override ValueTask<int> ReadAsync(byte[] buffer, int offset, int count)\r\n{\r\n    try\r\n    {\r\n        int bytesRead = Read(buffer, offset, count);\r\n        return new ValueTask<int>(bytesRead);\r\n    }\r\n    catch (Exception e)\r\n    {\r\n        return new ValueTask<int>(Task.FromException<int>(e));\r\n    }\r\n}<\/pre>\n<\/div>\n
ValueTask <TResult> and asynchronous completion<\/h2>\n
Being able to write an async method that can complete synchronously without incurring an additional allocation for the result type is a big win. This is why\u00a0ValueTask<TResult><\/code>\u00a0was added to .NET Core 2.0, and why new methods that are expected to be used on hot paths are now defined to return\u00a0ValueTask<TResult><\/code>\u00a0instead of\u00a0Task<TResult><\/code>. For example, when we added a new\u00a0ReadAsync<\/code>\u00a0overload to\u00a0Stream<\/code>\u00a0in .NET Core 2.1 in order to be able to pass in a\u00a0Memory<byte><\/code>\u00a0instead of a\u00a0byte[]<\/code>, we made the return type of that method be\u00a0ValueTask<int><\/code>. That way, Streams (which very often have a\u00a0ReadAsync<\/code>\u00a0method that completes synchronously, as in the earlier\u00a0MemoryStream<\/code>\u00a0example) can now be used with significantly less allocation.<\/p>\n
However, when working on very high-throughput services, we still care about avoiding as much allocation as possible, and that means thinking about reducing and removing allocations associated with asynchronous completion paths as well.<\/p>\n
With the\u00a0await<\/code>\u00a0model, for any operation that completes asynchronously we need to be able to hand back an object that represents the eventual completion of the operation: the caller needs to be able to hand off a callback that’ll be invoked when the operation completes, and that requires having a unique object on the heap that can serve as the conduit for this specific operation. It doesn’t, however, imply anything about whether that object can be reused once an operation completes. If the object can be reused, then an API can maintain a cache of one or more such objects, and reuse them for serialized operations, meaning it can’t use the same object for multiple in-flight async operations, but it can reuse an object for non-concurrent accesses.<\/p>\n
In .NET Core 2.1,\u00a0ValueTask<TResult><\/code>\u00a0was augmented to support such pooling and reuse. Rather than just being able to wrap a\u00a0TResult<\/code>\u00a0or a\u00a0Task<TResult><\/code>, a new interface was introduced,\u00a0IValueTaskSource<TResult><\/code>, and\u00a0ValueTask<TResult><\/code>\u00a0was augmented to be able to wrap that as well.\u00a0IValueTaskSource<TResult><\/code>\u00a0provides the core support necessary to represent an asynchronous operation to\u00a0ValueTask<TResult><\/code>\u00a0in a similar manner to how\u00a0Task<TResult><\/code>\u00a0does:<\/p>\n
\n
public interface IValueTaskSource<out TResult>\r\n{\r\n    ValueTaskSourceStatus GetStatus(short token);\r\n    void OnCompleted(Action<object> continuation, object state, short token, ValueTaskSourceOnCompletedFlags flags);\r\n    TResult GetResult(short token);\r\n}<\/pre>\n<\/div>\n
GetStatus<\/code>\u00a0is used to satisfy properties like\u00a0ValueTask<TResult>.IsCompleted<\/code>, returning an indication of whether the async operation is still pending or whether it’s completed and how (success or not).\u00a0OnCompleted<\/code>\u00a0is used by the\u00a0ValueTask<TResult><\/code>‘s awaiter to hook up the callback necessary to continue execution from an\u00a0await<\/code>\u00a0when the operation completes. And\u00a0GetResult<\/code>\u00a0is used to retrieve the result of the operation, such that after the operation completes, the awaiter can either get the\u00a0TResult<\/code>\u00a0or propagate any exception that may have occurred.<\/p>\n
Most developers should never have a need to see this interface: methods simply hand back a\u00a0ValueTask<TResult><\/code>\u00a0that may have been constructed to wrap an instance of this interface, and the consumer is none-the-wiser. The interface is primarily there so that developers of performance-focused APIs are able to avoid allocation.<\/p>\n
There are several such APIs in .NET Core 2.1. The most notable are\u00a0Socket.ReceiveAsync<\/code>\u00a0and\u00a0Socket.SendAsync<\/code>, with new overloads added in 2.1, e.g.<\/p>\n
\n
public ValueTask<int> ReceiveAsync(Memory<byte> buffer, SocketFlags socketFlags, CancellationToken cancellationToken = default);<\/pre>\n<\/div>\n
This overload returns a\u00a0ValueTask<int><\/code>. If the operation completes synchronously, it can simply construct a\u00a0ValueTask<int><\/code>\u00a0with the appropriate result, e.g.<\/p>\n
\n
int result = \u2026;\r\nreturn new ValueTask<int>(result);<\/pre>\n<\/div>\n
If it completes asynchronously, it can use a pooled object that implements this interface:<\/p>\n
\n
IValueTaskSource<int> vts = \u2026;\r\nreturn new ValueTask<int>(vts);<\/pre>\n<\/div>\n
The\u00a0Socket<\/code>\u00a0implementation maintains one such pooled object for receives and one for sends, such that as long as no more than one of each is outstanding at a time, these overloads will end up being allocation-free, even if they complete operations asynchronously. That’s then further surfaced through\u00a0NetworkStream<\/code>. For example, in .NET Core 2.1,\u00a0Stream<\/code>\u00a0exposes:<\/p>\n
\n
public virtual ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken cancellationToken);<\/pre>\n<\/div>\n
which\u00a0NetworkStream<\/code>\u00a0overrides.\u00a0NetworkStream.ReadAsync<\/code>\u00a0just delegates to\u00a0Socket.ReceiveAsync<\/code>, so the wins from\u00a0Socket<\/code>\u00a0translate to\u00a0NetworkStream<\/code>, and\u00a0NetworkStream.ReadAsync<\/code>\u00a0effectively becomes allocation-free as well.<\/p>\n
Non-generic ValueTask<\/h2>\n
When\u00a0ValueTask<TResult><\/code>\u00a0was introduced in .NET Core 2.0, it was purely about optimizing for the synchronous completion case, in order to avoid having to allocate a\u00a0Task<TResult><\/code>\u00a0to store the\u00a0TResult<\/code>\u00a0already available. That also meant that a non-generic\u00a0ValueTask<\/code>\u00a0wasn’t necessary: for the synchronous completion case, the\u00a0Task.CompletedTask<\/code>\u00a0singleton could just be returned from a\u00a0Task<\/code>-returning method, and was implicitly by the runtime for\u00a0async Task<\/code>\u00a0methods.<\/p>\n
With the advent of enabling even asynchronous completions to be allocation-free, however, a non-generic\u00a0ValueTask<\/code>\u00a0becomes relevant again. Thus, in .NET Core 2.1 we also introduced the non-generic\u00a0ValueTask<\/code>\u00a0and\u00a0IValueTaskSource<\/code>. These provide direct counterparts to the generic versions, usable in similar ways, just with a void result.<\/p>\n
Implementing IValueTaskSource \/ IValueTaskSource<T><\/h2>\n
Most developers should never need to implement these interfaces. They’re also not particularly easy to implement. If you decide you need to, there are several implementations internal to .NET Core 2.1 that can serve as a reference, e.g.<\/p>\n