Practical Use Case

To illustrate the benefits of ValueTask, we will analyze a common use case that many developers may encounter in their codebases. This example will show how implementing the ValueTask construct can lead to significant reductions in memory allocations, as ValueTask operates differently from Task. Let’s delve into a code example to clarify these distinctions.

Consider a service named GitHubService, designed to accept a GitHub username and retrieve user information from the public GitHub API. Upon fetching the user details, the service caches this information in memory for one hour, as demonstrated in the code snippet below:

public class GitHubService

{

private readonly IMemoryCache _cachedGitHubUserInfo = new MemoryCache(new MemoryCacheOptions());

private static readonly HttpClient HttpClient = new()

{

};

static GitHubService()

{

HttpClient.DefaultRequestHeaders.Add(HeaderNames.Accept, "application/vnd.github.v3+json");

HttpClient.DefaultRequestHeaders.Add(HeaderNames.UserAgent, $"Medium-Story-{Environment.MachineName}");

}

public async Task<GitHubUserInfo> GetGitHubUserInfoAsyncTask(string username)

{

var cacheKey = ("github-", username);

var gitHubUserInfo = _cachedGitHubUserInfo.Get(cacheKey);

if (gitHubUserInfo is null)

{

var response = await HttpClient.GetAsync($"/users/{username}");

if (response.StatusCode == HttpStatusCode.OK)

{

gitHubUserInfo = await response.Content.ReadFromJsonAsync<GitHubUserInfo>();

_cachedGitHubUserInfo.Set(cacheKey, gitHubUserInfo, TimeSpan.FromHours(1));

}

}

return gitHubUserInfo;

}

}

The method returns an object containing the GitHub user's username, profile URL, name, and company, encapsulated in a record called GitHubUserInfo:

public record GitHubUserInfo(

[property: JsonPropertyName("login")] string Username,

[property: JsonPropertyName("html_url")] string ProfileUrl,

[property: JsonPropertyName("name")] string Name,

[property: JsonPropertyName("company")] string Company);

This example fits into a larger system that manages information about clients, which in this case, happen to be developers. There are numerous situations where you may retrieve data from an external API, store it in memory, and subsequently utilize it in your application. As always, leveraging an async Task method is recommended for such I/O operations to prevent blocking the thread.

However, the challenge arises from returning a Task, which is a reference type allocated on the heap. In our scenario, we only need to return a Task once every hour for a specific GitHub username; during other instances, we can simply return the cached user information.

ValueTask to the Rescue

This is where ValueTask becomes beneficial. In essence, ValueTask acts as a discriminated union that can represent either a T (a specific type) or a Task. By substituting the Task return type with ValueTask, we can reclaim memory allocations, as the Task memory is only allocated when it is necessary to return a Task.

When we retrieve user information from the memory cache, we avoid unnecessary memory allocations. To modify the GetGitHubUserInfoAsyncTask method to return a ValueTask, we can create a new method called GetGitHubUserInfoAsyncValueTask within GitHubService, as shown in the following code snippet:

public async ValueTask<GitHubUserInfo> GetGitHubUserInfoAsyncValueTask(string username)

{

var cacheKey = ("github-", username);

var gitHubUserInfo = _cachedGitHubUserInfo.Get(cacheKey);

if (gitHubUserInfo is null)

{

var response = await HttpClient.GetAsync($"/users/{username}");

if (response.StatusCode == HttpStatusCode.OK)

{

gitHubUserInfo = await response.Content.ReadFromJsonAsync<GitHubUserInfo>();

_cachedGitHubUserInfo.Set(cacheKey, gitHubUserInfo, TimeSpan.FromHours(1));

}

}

return gitHubUserInfo;

}

Benchmarking Analysis: Comparing Task and ValueTask

To comprehend the differences between Task and ValueTask, we will conduct a benchmark utilizing the BenchmarkDotNet library. We will create a class named GitHubServiceBenchmarks and annotate it with the MemoryDiagnoser attribute to measure memory allocation during the benchmarks:

[MemoryDiagnoser]

public class GitHubServiceBenchmarks

{

private static readonly GitHubService GitHubService = new();

[Benchmark]

public async Task<GitHubUserInfo> GetGitHubUserInfoAsyncTask()

{

return await GitHubService.GetGitHubUserInfoAsyncTask("ormikopo1988");

}

}

In this initial benchmark, we simply return a Task of GitHubUserInfo. During the first execution, our cache will be empty for the specified GitHub username, prompting a call to the GitHub API. Upon receiving a response, we immediately cache the result for one hour, adhering to the Cache-Aside pattern. For subsequent requests for the same GitHub username within the hour, the GitHubUserInfo object will be retrieved from memory, which is typical behavior when the information remains unchanged.

Next, we will implement a second benchmark that calls the GetGitHubUserInfoAsyncValueTask method, which returns a ValueTask of GitHubUserInfo:

[Benchmark]

public async ValueTask<GitHubUserInfo> GetGitHubUserInfoAsyncValueTask()

{

return await GitHubService.GetGitHubUserInfoAsyncValueTask("ormikopo1988");

}

We do not anticipate significant differences in speed; the focus is on memory usage and the workload on the garbage collector. Running the benchmark may reveal that Task is marginally faster at times, while ValueTask may outperform in other instances. For simplicity, we assume comparable speeds for both methods.

Benchmark Results

Interestingly, the first benchmark shows that Gen0 garbage collection and memory allocation is reduced by 72 bytes when using ValueTask. You may wonder if this reduction is meaningful. Consider that it amounts to 72 bytes saved every time the method is called, compounded by each caller returning a Task.

Since ValueTask internally utilizes a Task, the second benchmark returns a Task even though GetGitHubUserInfoAsyncValueTask itself returns a ValueTask. Therefore, we might not fully leverage ValueTask's advantages.

To optimize further, we could create a third benchmark, GetGitHubUserInfoAsyncValueTaskTimesTwo, which would also return a ValueTask:

[Benchmark]

public async ValueTask<GitHubUserInfo> GetGitHubUserInfoAsyncValueTaskTimesTwo()

{

return await GitHubService.GetGitHubUserInfoAsyncValueTask("ormikopo1988");

}

The results from this benchmark would only apply if the parent method can also benefit from using ValueTask, meaning it does not invoke any I/O operations itself. If this condition holds, the memory allocation will be even lower since we eliminate the second Task allocation, achieving a cascading effect.

Crucially, once we await a ValueTask, we should avoid re-awaiting it, as this diverges from Task behavior. ValueTask should not be used in constructs like Task.WhenAll or Task.WaitAll, as doing so can lead to complications.

In our example, the third benchmark demonstrates an additional 72 bytes saved due to the second allocation reduction. Therefore, if we handle 1000 requests per second and apply this technique to 50 or 100 of them, the memory savings can be substantial. The use case explored serves as an ideal introduction to ValueTask, but other scenarios exist where it can be advantageous, though they fall outside this article's scope.

Conclusion

Through practical examples and benchmark analysis, this article illustrates how transitioning to ValueTask can substantially decrease memory allocations, particularly in scenarios involving cached results. While ValueTask presents compelling advantages, it is essential to implement it thoughtfully, considering its intricacies. By selectively incorporating ValueTask, developers can unlock performance improvements, especially in high-throughput applications.