ValueTask in C# — When, Why and How to Use It Correctly

using System;
using System.Threading.Tasks;
using System.Runtime.CompilerServices;

// Run this in a BenchmarkDotNet project to see the allocation delta yourself.
// Or run it as a quick console app and watch the GC collection count.
public class AllocationComparison
{
    // Simulated in-memory cache — 90% hit rate
    private static readonly string? _cachedGreeting = "Hello, World!";

    // --- APPROACH 1: Always allocates a Task object on the heap ---
    public static Task<string> GetGreetingWithTask(bool forceAsync)
    {
        if (!forceAsync && _cachedGreeting is not null)
        {
            // Task.FromResult boxes the string into a new Task<string> object.
            // This heap allocation happens EVERY CALL even though we have the answer.
            return Task.FromResult(_cachedGreeting);
        }

        // Genuine async path — a Task allocation here is expected and justified.
        return SimulateSlowDatabaseCallAsync();
    }

    // --- APPROACH 2: Zero allocation on the synchronous fast path ---
    public static ValueTask<string> GetGreetingWithValueTask(bool forceAsync)
    {
        if (!forceAsync && _cachedGreeting is not null)
        {
            // ValueTask<string> is a struct — the string sits inside the struct itself.
            // No heap object created. The struct lives in the caller's stack frame.
            return new ValueTask<string>(_cachedGreeting);
        }

        // When we must go async, we wrap a real Task inside the ValueTask.
        // The allocation cost here is the same as Task — but this path is rare.
        return new ValueTask<string>(SimulateSlowDatabaseCallAsync());
    }

    private static async Task<string> SimulateSlowDatabaseCallAsync()
    {
        await Task.Delay(50); // pretend this is an actual DB round-trip
        return "Hello from database!";
    }

    public static async Task Main(string[] args)
    {
        int iterations = 100_000;
        long gcBefore, gcAfter;

        // --- Measure Task allocations ---
        GC.Collect(); // baseline collection
        gcBefore = GC.CollectionCount(0); // generation-0 count before

        for (int i = 0; i < iterations; i++)
        {
            // Synchronous fast path — 'false' means "use cache"
            string result = await GetGreetingWithTask(forceAsync: false);
            _ = result; // prevent compiler optimisation removing the call
        }

        gcAfter = GC.CollectionCount(0);
        Console.WriteLine($"Task path — Gen0 GC collections: {gcAfter - gcBefore}");

        // --- Measure ValueTask allocations ---
        GC.Collect();
        gcBefore = GC.CollectionCount(0);

        for (int i = 0; i < iterations; i++)
        {
            // Same synchronous fast path — struct returned, no heap pressure
            string result = await GetGreetingWithValueTask(forceAsync: false);
            _ = result;
        }

        gcAfter = GC.CollectionCount(0);
        Console.WriteLine($"ValueTask path — Gen0 GC collections: {gcAfter - gcBefore}");
    }
}

using System;
using System.Threading;
using System.Threading.Tasks;
using System.Threading.Tasks.Sources;
using System.Collections.Generic;

// A minimal, educational IValueTaskSource<int> implementation.
// In real code, Microsoft.Toolkit.HighPerformance or Channel<T> provide production-grade versions.
public class PooledValueTaskSource : IValueTaskSource<int>
{
    // Version token — increments each time this source is reused from the pool.
    // ValueTask stores this token at creation time. If you await twice and the token
    // has changed, the ValueTask is reading stale state.
    private short _currentToken;

    private int _result;
    private bool _isCompleted;
    private Action<object?>? _continuation; // the async state machine callback
    private object? _continuationState;

    // Called by the ValueTask machinery to get the result.
    // The token MUST match — this is the safety check.
    public int GetResult(short token)
    {
        if (token != _currentToken)
            throw new InvalidOperationException(
                "ValueTask was awaited after its underlying source was recycled. " +
                "Never await the same ValueTask more than once.");

        if (!_isCompleted)
            throw new InvalidOperationException("Result not yet available.");

        int capturedResult = _result;

        // Recycle: bump the token so stale awaits are caught immediately.
        _currentToken++;
        _isCompleted = false;
        _continuation = null;
        Console.WriteLine($"[Pool] Source recycled. New token is {_currentToken}.");

        return capturedResult;
    }

    public ValueTaskSourceStatus GetStatus(short token)
    {
        if (token != _currentToken)
            throw new InvalidOperationException("Stale token — source has been recycled.");

        return _isCompleted ? ValueTaskSourceStatus.Succeeded : ValueTaskSourceStatus.Pending;
    }

    public void OnCompleted(
        Action<object?> continuation,
        object? state,
        short token,
        ValueTaskSourceOnCompletedFlags flags)
    {
        _continuation = continuation;
        _continuationState = state;
    }

    // Simulates the I/O completing and signalling the awaiter.
    public void SignalCompletion(int result)
    {
        _result = result;
        _isCompleted = true;
        Console.WriteLine($"[Source] Signalled completion with result: {result}");
        _continuation?.Invoke(_continuationState);
    }

    // Returns a ValueTask that points to THIS source with the current token.
    public ValueTask<int> AsValueTask() => new ValueTask<int>(this, _currentToken);
}

public class IValueTaskSourceDemo
{
    public static async Task Main(string[] args)
    {
        var source = new PooledValueTaskSource();

        // Simulate: some I/O completes in the background after 100ms
        var backgroundWork = Task.Run(async () =>
        {
            await Task.Delay(100);
            source.SignalCompletion(result: 42);
        });

        // Get a ValueTask from the pooled source
        ValueTask<int> valueTask = source.AsValueTask();
        Console.WriteLine("[Main] Awaiting ValueTask...");

        int answer = await valueTask; // first await — CORRECT
        Console.WriteLine($"[Main] Result: {answer}");

        // --- DEMONSTRATION OF THE BUG ---
        // Do NOT do this in real code. We show it so you recognise the exception.
        try
        {
            // The source has been recycled after first GetResult() call.
            // Token mismatch will be caught here.
            int staleAnswer = await valueTask; // second await — WRONG
            Console.WriteLine($"[Main] Stale result: {staleAnswer}"); // never reaches here
        }
        catch (InvalidOperationException ex)
        {
            Console.WriteLine($"[Main] Caught expected error: {ex.Message}");
        }

        await backgroundWork;
    }
}

using System;
using System.Collections.Concurrent;
using System.Threading.Tasks;
using System.Net.Http;

// A realistic, production-style HTTP response cache.
// The synchronous cache-hit path (majority of calls) returns ValueTask with zero allocation.
// The actual HTTP call (minority of calls) wraps a real Task inside ValueTask.
public class HttpResponseCache
{
    private readonly HttpClient _httpClient;

    // Thread-safe dictionary acting as our L1 in-memory cache
    private readonly ConcurrentDictionary<string, string> _cache = new();

    public HttpResponseCache(HttpClient httpClient)
    {
        _httpClient = httpClient;
    }

    // --- ValueTask is the RIGHT choice here because:
    //   1. Cache hits (synchronous path) are the majority case in steady-state.
    //   2. A single caller per URL awaits it — no fan-out.
    //   3. We never need to await the same ValueTask twice.
    public ValueTask<string> GetContentAsync(string url)
    {
        // FAST PATH — cache hit. Returns synchronously as a struct.
        // Zero heap allocation. The string sits directly in the ValueTask struct.
        if (_cache.TryGetValue(url, out string? cachedContent))
        {
            Console.WriteLine($"[Cache] HIT for {url} — no allocation, no await suspension");
            return new ValueTask<string>(cachedContent);
        }

        // SLOW PATH — genuine HTTP call needed.
        // We pay the Task allocation cost here, but this is justified — the method truly suspends.
        Console.WriteLine($"[Cache] MISS for {url} — initiating HTTP request");
        return new ValueTask<string>(FetchAndCacheAsync(url));
    }

    private async Task<string> FetchAndCacheAsync(string url)
    {
        // Real I/O — suspension happens here. Task allocation is appropriate.
        string content = await _httpClient.GetStringAsync(url);

        // Store in cache so the NEXT call hits the fast path
        _cache[url] = content;

        Console.WriteLine($"[Cache] Stored {content.Length} chars for {url}");
        return content;
    }
}

// --- Example showing Task is the RIGHT choice for fan-out scenarios ---
public class FanOutExample
{
    // DON'T use ValueTask here — multiple awaits on the same logical operation.
    // Convert to Task so each awaiter gets a stable, reusable object.
    public static async Task DemonstrateWhyTaskWinsForFanOut(HttpResponseCache cache)
    {
        string url = "https://example.com";

        // WRONG: storing a ValueTask and awaiting it from two places
        // ValueTask<string> sharedTask = cache.GetContentAsync(url); // DON'T
        // string a = await sharedTask; // first await — ok
        // string b = await sharedTask; // second await — UNDEFINED BEHAVIOUR

        // CORRECT: convert to Task if you need to share or await multiple times
        Task<string> sharedTask = cache.GetContentAsync(url).AsTask();

        // Now both awaits are safe — Task can be awaited any number of times
        string firstResult = await sharedTask;
        string secondResult = await sharedTask; // safe because it's a Task now

        Console.WriteLine($"Fan-out result 1: {firstResult.Substring(0, Math.Min(30, firstResult.Length))}...");
        Console.WriteLine($"Fan-out result 2 (same task): {secondResult.Substring(0, Math.Min(30, secondResult.Length))}...");
    }

    public static async Task Main(string[] args)
    {
        using var httpClient = new HttpClient();
        var cache = new HttpResponseCache(httpClient);

        // First call — cache miss, real HTTP request
        string content1 = await cache.GetContentAsync("https://example.com");
        Console.WriteLine($"First call — got {content1.Length} chars\n");

        // Second call — cache hit, zero allocation
        string content2 = await cache.GetContentAsync("https://example.com");
        Console.WriteLine($"Second call — got {content2.Length} chars\n");

        // Fan-out demo
        await DemonstrateWhyTaskWinsForFanOut(cache);
    }
}

// Install BenchmarkDotNet: dotnet add package BenchmarkDotNet
// Run with: dotnet run -c Release
// The [MemoryDiagnoser] attribute is what shows you allocations per operation.

using System;
using System.Runtime.CompilerServices;
using System.Threading.Tasks;
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;

[MemoryDiagnoser]        // shows bytes allocated per operation
[RankColumn]             // adds a rank column so you can eyeball the winner
public class ValueTaskBenchmarks
{
    private const int CachedValue = 99;

    // --- Baseline: Task.FromResult on the synchronous path ---
    // Allocates a Task<int> object every call (except JIT cache for small ints).
    [Benchmark(Baseline = true)]
    public async Task<int> GetWithTask()
    {
        // Task.FromResult(99) — int 99 is within the JIT cache range (0-9 is cached,
        // but 99 is NOT, so this DOES allocate on most runtimes).
        return await Task.FromResult(CachedValue);
    }

    // --- ValueTask on synchronous path: struct, no heap allocation ---
    [Benchmark]
    public async ValueTask<int> GetWithValueTask()
    {
        // Struct returned directly — the int lives inside the ValueTask struct.
        // No heap allocation. Awaiting a completed ValueTask is optimized by the runtime.
        return await new ValueTask<int>(CachedValue);
    }

    // --- Pooled state machine: .NET 6+ feature that also pools the async machinery ---
    // Requires the method to be marked with the builder attribute.
    [Benchmark]
    [AsyncMethodBuilder(typeof(PoolingAsyncValueTaskMethodBuilder<int>))]
    public async ValueTask<int> GetWithPooledValueTask()
    {
        // Same synchronous fast path, but now even the async state machine
        // is sourced from a pool rather than allocated fresh.
        return await new ValueTask<int>(CachedValue);
    }

    // --- Truly async path: shows that ValueTask has no advantage when you actually suspend ---
    [Benchmark]
    public async ValueTask<int> GetWithValueTaskActuallyAsync()
    {
        // This DOES suspend — state machine is allocated here regardless.
        // ValueTask provides no benefit over Task on this path in most cases.
        await Task.Yield();
        return CachedValue;
    }
}

// Entry point — BenchmarkDotNet handles the rest
public class Program
{
    public static void Main(string[] args)
    {
        BenchmarkRunner.Run<ValueTaskBenchmarks>();
    }
}