Switch to ValueTask<T> to avoid allocations from commands

When commands complete before a method returning, we can avoid a Task allocation altogether by using ValueTask instead of Task. Since the goal of executing a command is typically to retrieve a value and use that right-away, the optimization makes sense in general.

Aligns with the new NotifyAsync for events too.

Fixes #125

Author: kzu

readme.md

@@ -45,7 +45,7 @@ The events-based API surface on the message bus is simple enough:
 ```csharp
 public interface IMessageBus
 {
-    void Notify<TEvent>(TEvent e);
+    ValueTask NotifyAsync<TEvent>(TEvent e);
     IObservable<TEvent> Observe<TEvent>();
 }
 ```
@@ -132,9 +132,9 @@ public interface IMessageBus
     // sync value-returning
     TResult Execute<TResult>(ICommand<TResult> command);
     // async void
-    Task ExecuteAsync(IAsyncCommand command, CancellationToken cancellation);
+    ValueTask ExecuteAsync(IAsyncCommand command, CancellationToken cancellation);
     // async value-returning
-    Task<TResult> ExecuteAsync<TResult>(IAsyncCommand<TResult> command, CancellationToken cancellation);
+    ValueTask<TResult> ExecuteAsync<TResult>(IAsyncCommand<TResult> command, CancellationToken cancellation);
     // async stream
     IAsyncEnumerable<TResult> ExecuteStream<TResult>(IStreamCommand<TResult> command, CancellationToken cancellation);
 }
@@ -150,7 +150,7 @@ class FindDocumentsHandler : IAsyncCommandHandler<FindDocument, IEnumerable<stri
 {
     public bool CanExecute(FindDocument command) => !string.IsNullOrEmpty(command.Filter);
 
-    public Task<IEnumerable<string>> ExecuteAsync(FindDocument command, CancellationToken cancellation)
+    public ValueTask<IEnumerable<string>> ExecuteAsync(FindDocument command, CancellationToken cancellation)
         => // evaluate command.Filter across all documents and return matches
 }
 ```
@@ -411,6 +411,16 @@ builder.Services.AddServices();
 
 <!-- #duck -->
 
+<!-- #perf -->
+# Performance
+
+The performance of Merq is on par with the best implementations of the 
+the same pattern, for example [MediatR](https://www.nuget.org/packages/mediatr):
+
+<!-- include ./src/Merq.Benchmarks/BenchmarkDotNet.Artifacts/results/Merq.MerqVsMediatR.Benchmark-report-github.md -->
+
+<!-- #perf -->
+
 <!-- #ci -->
 
 # Dogfooding

src/Merq.Benchmarks/MerqVsMediatR.cs

@@ -2,7 +2,6 @@
 using System.Threading;
 using System.Threading.Tasks;
 using BenchmarkDotNet.Attributes;
-using BenchmarkDotNet.Diagnostics.Windows.Configs;
 using MediatR;
 using Microsoft.Extensions.DependencyInjection;
 
@@ -73,5 +72,5 @@ public class PingMerqAsync : IAsyncCommand<string>;
 public class PingMerqAsyncHandler : IAsyncCommandHandler<PingMerqAsync, string>
 {
     public bool CanExecute(PingMerqAsync command) => true;
-    public Task<string> ExecuteAsync(PingMerqAsync command, CancellationToken cancellation) => Task.FromResult("Pong");
+    public ValueTask<string> ExecuteAsync(PingMerqAsync command, CancellationToken cancellation) => ValueTask.FromResult("Pong");
 }

src/Merq.Benchmarks/Program.cs

@@ -1,5 +1,4 @@
-using BenchmarkDotNet.Configs;
-using BenchmarkDotNet.Running;
+using BenchmarkDotNet.Running;
 using Merq.MerqVsMediatR;
 
 // Debug in-process configuration

src/Merq.Core/MessageBus.cs

@@ -238,7 +238,7 @@ public TResult Execute<TResult>(ICommand<TResult> command, [CallerMemberName] st
     }
 
     /// <inheritdoc/>
-    public Task ExecuteAsync(IAsyncCommand command, CancellationToken cancellation = default, [CallerMemberName] string? callerName = default, [CallerFilePath] string? callerFile = default, [CallerLineNumber] int? callerLine = default)
+    public ValueTask ExecuteAsync(IAsyncCommand command, CancellationToken cancellation = default, [CallerMemberName] string? callerName = default, [CallerFilePath] string? callerFile = default, [CallerLineNumber] int? callerLine = default)
     {
         var type = GetCommandType(command);
         using var activity = StartCommandActivity(type, command, callerName, callerFile, callerLine);
@@ -266,7 +266,7 @@ public Task ExecuteAsync(IAsyncCommand command, CancellationToken cancellation =
     }
 
     /// <inheritdoc/>
-    public Task<TResult> ExecuteAsync<TResult>(IAsyncCommand<TResult> command, CancellationToken cancellation = default, [CallerMemberName] string? callerName = default, [CallerFilePath] string? callerFile = default, [CallerLineNumber] int? callerLine = default)
+    public ValueTask<TResult> ExecuteAsync<TResult>(IAsyncCommand<TResult> command, CancellationToken cancellation = default, [CallerMemberName] string? callerName = default, [CallerFilePath] string? callerFile = default, [CallerLineNumber] int? callerLine = default)
     {
         var type = GetCommandType(command);
         using var activity = StartCommandActivity(type, command, callerName, callerFile, callerLine);
@@ -278,7 +278,7 @@ public Task<TResult> ExecuteAsync<TResult>(IAsyncCommand<TResult> command, Cance
                 // For public types, we can use the faster dynamic dispatch approach
                 return WithResult<TResult>().ExecuteAsync((dynamic)command, cancellation);
 #endif
-            return (Task<TResult>)resultAsyncExecutors.GetOrAdd(type, type
+            return (ValueTask<TResult>)resultAsyncExecutors.GetOrAdd(type, type
                 => (ResultAsyncDispatcher)Activator.CreateInstance(
                     typeof(ResultAsyncDispatcher<,>).MakeGenericType(type, typeof(TResult)),
                     this)!)
@@ -548,7 +548,7 @@ commandType is not null &&
         throw new InvalidOperationException($"No service for type '{typeof(ICommandHandler<TCommand>)}' has been registered.");
     }
 
-    Task ExecuteAsyncCore<TCommand>(TCommand command, CancellationToken cancellation) where TCommand : IAsyncCommand
+    ValueTask ExecuteAsyncCore<TCommand>(TCommand command, CancellationToken cancellation) where TCommand : IAsyncCommand
     {
         var handler = services.GetService<IAsyncCommandHandler<TCommand>>();
         if (handler != null)
@@ -608,7 +608,7 @@ commandType is not null &&
         throw new InvalidOperationException($"No service for type '{typeof(ICommandHandler<TCommand, TResult>)}' has been registered.");
     }
 
-    Task<TResult> ExecuteAsyncCore<TCommand, TResult>(TCommand command, CancellationToken cancellation) where TCommand : IAsyncCommand<TResult>
+    ValueTask<TResult> ExecuteAsyncCore<TCommand, TResult>(TCommand command, CancellationToken cancellation) where TCommand : IAsyncCommand<TResult>
     {
         var handler = services.GetService<IAsyncCommandHandler<TCommand, TResult>>();
         if (handler != null)
@@ -681,7 +681,7 @@ readonly struct With<TResult>(MessageBus bus)
         public TResult Execute<TCommand>(TCommand command) where TCommand : ICommand<TResult>
             => bus.ExecuteCore<TCommand, TResult>(command);
 
-        public Task<TResult> ExecuteAsync<TCommand>(TCommand command, CancellationToken cancellation) where TCommand : IAsyncCommand<TResult>
+        public ValueTask<TResult> ExecuteAsync<TCommand>(TCommand command, CancellationToken cancellation) where TCommand : IAsyncCommand<TResult>
             => bus.ExecuteAsyncCore<TCommand, TResult>(command, cancellation);
 
 #if NET6_0_OR_GREATER
@@ -751,12 +751,12 @@ class ResultDispatcher<TCommand, TResult>(MessageBus bus) : ResultDispatcher whe
 
     abstract class VoidAsyncDispatcher
     {
-        public abstract Task ExecuteAsync(IExecutable command, CancellationToken cancellation);
+        public abstract ValueTask ExecuteAsync(IExecutable command, CancellationToken cancellation);
     }
 
     class VoidAsyncDispatcher<TCommand>(MessageBus bus) : VoidAsyncDispatcher where TCommand : IAsyncCommand
     {
-        public override Task ExecuteAsync(IExecutable command, CancellationToken cancellation)
+        public override ValueTask ExecuteAsync(IExecutable command, CancellationToken cancellation)
             => bus.ExecuteAsyncCore((TCommand)command, cancellation);
     }
 

src/Merq.Tests/MessageBusServiceSpec.cs

@@ -204,7 +204,7 @@ public async Task when_executing_async_command_without_handler_then_throws()
         Assert.False(bus.CanExecute(new AsyncCommand()));
         Assert.False(bus.CanHandle<AsyncCommand>());
         Assert.False(bus.CanHandle(new AsyncCommand()));
-        await Assert.ThrowsAsync<InvalidOperationException>(() => bus.ExecuteAsync(new AsyncCommand(), CancellationToken.None));
+        await Assert.ThrowsAsync<InvalidOperationException>(async () => await bus.ExecuteAsync(new AsyncCommand(), CancellationToken.None));
     }
 
     [Fact]
@@ -213,7 +213,7 @@ public async Task when_executing_async_command_with_result_without_handler_then_
         Assert.False(bus.CanExecute(new AsyncCommandWithResult()));
         Assert.False(bus.CanHandle<AsyncCommandWithResult>());
         Assert.False(bus.CanHandle(new AsyncCommandWithResult()));
-        await Assert.ThrowsAsync<InvalidOperationException>(() => bus.ExecuteAsync(new AsyncCommandWithResult(), CancellationToken.None));
+        await Assert.ThrowsAsync<InvalidOperationException>(async () => await bus.ExecuteAsync(new AsyncCommandWithResult(), CancellationToken.None));
     }
 
     [Fact]

src/Merq/IAsyncCommandHandler.cs

@@ -23,7 +23,7 @@ public interface IAsyncCommandHandler<in TCommand> : IAsyncCommandHandler, IExec
     /// </summary>
     /// <param name="command">The command parameters for the execution.</param>
     /// <param name="cancellation">Cancellation token to cancel command execution.</param>
-    Task ExecuteAsync(TCommand command, CancellationToken cancellation = default);
+    ValueTask ExecuteAsync(TCommand command, CancellationToken cancellation = default);
 }
 
 /// <summary>
@@ -44,5 +44,5 @@ public interface IAsyncCommandHandler<in TCommand, TResult> : IAsyncCommandHandl
     /// <param name="command">The command parameters for the execution.</param>
     /// <param name="cancellation">Cancellation token to cancel command execution.</param>
     /// <returns>The result of the execution.</returns>
-    Task<TResult> ExecuteAsync(TCommand command, CancellationToken cancellation = default);
+    ValueTask<TResult> ExecuteAsync(TCommand command, CancellationToken cancellation = default);
 }

src/Merq/IMessageBus.cs

@@ -68,7 +68,7 @@ public interface IMessageBus
     /// <param name="callerName">Optional calling member name, provided by default by the compiler.</param>
     /// <param name="callerFile">Optional calling file name, provided by default by the compiler.</param>
     /// <param name="callerLine">Optional calling line number, provided by default by the compiler.</param>
-    Task ExecuteAsync(IAsyncCommand command, CancellationToken cancellation = default, [CallerMemberName] string? callerName = default, [CallerFilePath] string? callerFile = default, [CallerLineNumber] int? callerLine = default);
+    ValueTask ExecuteAsync(IAsyncCommand command, CancellationToken cancellation = default, [CallerMemberName] string? callerName = default, [CallerFilePath] string? callerFile = default, [CallerLineNumber] int? callerLine = default);
 
     /// <summary>
     /// Executes the given asynchronous command and returns a result from it.
@@ -80,7 +80,7 @@ public interface IMessageBus
     /// <param name="callerFile">Optional calling file name, provided by default by the compiler.</param>
     /// <param name="callerLine">Optional calling line number, provided by default by the compiler.</param>
     /// <returns>The result of executing the command.</returns>
-    Task<TResult> ExecuteAsync<TResult>(IAsyncCommand<TResult> command, CancellationToken cancellation = default, [CallerMemberName] string? callerName = default, [CallerFilePath] string? callerFile = default, [CallerLineNumber] int? callerLine = default);
+    ValueTask<TResult> ExecuteAsync<TResult>(IAsyncCommand<TResult> command, CancellationToken cancellation = default, [CallerMemberName] string? callerName = default, [CallerFilePath] string? callerFile = default, [CallerLineNumber] int? callerLine = default);
 
 #if NET6_0_OR_GREATER
     /// <summary>

src/Merq/PublicAPI.Shipped.txt

@@ -2,10 +2,10 @@
 Merq.IAsyncCommand
 Merq.IAsyncCommand<TResult>
 Merq.IAsyncCommandHandler
-Merq.IAsyncCommandHandler<TCommand, TResult>
-Merq.IAsyncCommandHandler<TCommand, TResult>.ExecuteAsync(TCommand command, System.Threading.CancellationToken cancellation = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<TResult>!
 Merq.IAsyncCommandHandler<TCommand>
-Merq.IAsyncCommandHandler<TCommand>.ExecuteAsync(TCommand command, System.Threading.CancellationToken cancellation = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
+Merq.IAsyncCommandHandler<TCommand, TResult>
+Merq.IAsyncCommandHandler<TCommand, TResult>.ExecuteAsync(TCommand command, System.Threading.CancellationToken cancellation = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask<TResult>
+Merq.IAsyncCommandHandler<TCommand>.ExecuteAsync(TCommand command, System.Threading.CancellationToken cancellation = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask
 Merq.ICanExecute<TCommand>
 Merq.ICanExecute<TCommand>.CanExecute(TCommand command) -> bool
 Merq.ICommand
@@ -26,12 +26,14 @@ Merq.IMessageBus.CanHandle(Merq.IExecutable! command) -> bool
 Merq.IMessageBus.CanHandle<TCommand>() -> bool
 Merq.IMessageBus.Execute(Merq.ICommand! command, string? callerName = null, string? callerFile = null, int? callerLine = null) -> void
 Merq.IMessageBus.Execute<TResult>(Merq.ICommand<TResult>! command, string? callerName = null, string? callerFile = null, int? callerLine = null) -> TResult
-Merq.IMessageBus.ExecuteAsync(Merq.IAsyncCommand! command, System.Threading.CancellationToken cancellation = default(System.Threading.CancellationToken), string? callerName = null, string? callerFile = null, int? callerLine = null) -> System.Threading.Tasks.Task!
-Merq.IMessageBus.ExecuteAsync<TResult>(Merq.IAsyncCommand<TResult>! command, System.Threading.CancellationToken cancellation = default(System.Threading.CancellationToken), string? callerName = null, string? callerFile = null, int? callerLine = null) -> System.Threading.Tasks.Task<TResult>!
+Merq.IMessageBus.ExecuteAsync(Merq.IAsyncCommand! command, System.Threading.CancellationToken cancellation = default(System.Threading.CancellationToken), string? callerName = null, string? callerFile = null, int? callerLine = null) -> System.Threading.Tasks.ValueTask
+Merq.IMessageBus.ExecuteAsync<TResult>(Merq.IAsyncCommand<TResult>! command, System.Threading.CancellationToken cancellation = default(System.Threading.CancellationToken), string? callerName = null, string? callerFile = null, int? callerLine = null) -> System.Threading.Tasks.ValueTask<TResult>
 Merq.IMessageBus.NotifyAsync<TEvent>(TEvent e, string? callerName = null, string? callerFile = null, int? callerLine = null) -> System.Threading.Tasks.ValueTask
 Merq.IMessageBus.Observe<TEvent>() -> System.IObservable<TEvent>!
 Merq.IMessageBusExtensions
 static Merq.IMessageBusExtensions.Execute<TCommand>(this Merq.IMessageBus! bus, string? callerName = null, string? callerFile = null, int? callerLine = null) -> void
 static Merq.IMessageBusExtensions.Notify<TEvent>(this Merq.IMessageBus! bus, string? callerName = null, string? callerFile = null, int? callerLine = null) -> void
 static Merq.IMessageBusExtensions.Notify<TEvent>(this Merq.IMessageBus! bus, TEvent e, string? callerName = null, string? callerFile = null, int? callerLine = null) -> void
 static Merq.IMessageBusExtensions.NotifyAsync<TEvent>(this Merq.IMessageBus! bus, string? callerName = null, string? callerFile = null, int? callerLine = null) -> System.Threading.Tasks.ValueTask
+Merq.ValueTaskExtensions
+static Merq.ValueTaskExtensions.Forget(this System.Threading.Tasks.ValueTask task) -> void

src/Merq/ValueTaskExtensions.cs

@@ -0,0 +1,44 @@
+using System.ComponentModel;
+using System.Threading.Tasks;
+
+namespace Merq;
+
+/// <summary>
+/// Provides the <see cref="Forget"/> extension method to <see cref="ValueTask"/>.
+/// </summary>
+[EditorBrowsable(EditorBrowsableState.Never)]
+public static class ValueTaskExtensions
+{
+    /// <summary>
+    /// Observes the value task to avoid exceptions.
+    /// </summary>
+    public static void Forget(this ValueTask task)
+    {
+        // note: this code is inspired by a tweet from Ben Adams: https://twitter.com/ben_a_adams/status/1045060828700037125
+        // Only care about tasks that may fault (not completed) or are faulted,
+        // so fast-path for SuccessfullyCompleted and Canceled tasks.
+        if (!task.IsCompleted || task.IsFaulted)
+        {
+            // use "_" (Discard operation) to remove the warning IDE0058: Because this call is not awaited, execution of the current method continues before the call is completed
+            // https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/discards?WT.mc_id=DT-MVP-5003978#a-standalone-discard
+#pragma warning disable CA2012
+            _ = ForgetAwaited(task);
+#pragma warning restore CA2012
+        }
+
+        // Allocate the async/await state machine only when needed for performance reasons.
+        // More info about the state machine: https://blogs.msdn.microsoft.com/seteplia/2017/11/30/dissecting-the-async-methods-in-c/?WT.mc_id=DT-MVP-5003978
+        async static ValueTask ForgetAwaited(ValueTask task)
+        {
+            try
+            {
+                // No need to resume on the original SynchronizationContext, so use ConfigureAwait(false)
+                await task.ConfigureAwait(false);
+            }
+            catch
+            {
+                // Nothing to do here
+            }
+        }
+    }
+}

src/Samples/Library1/Commands.cs

@@ -24,48 +24,35 @@ public void Execute(NoOp command) { }
 }
 
 [Service]
-public class EchoHandler : ICommandHandler<Echo, string>
+public class EchoHandler(IMessageBus bus) : ICommandHandler<Echo, string>
 {
-    readonly IMessageBus? bus;
-
-    public EchoHandler() { }
-
-    public EchoHandler(IMessageBus bus) => this.bus = bus;
-
     public bool CanExecute(Echo command) => !string.IsNullOrEmpty(command.Message);
 
     public string Execute(Echo command)
     {
         if (string.IsNullOrEmpty(command.Message))
             throw new NotSupportedException("Cannot echo an empty or null message");
 
-        bus?.Notify(new OnDidSay(command.Message));
+        bus.NotifyAsync(new OnDidSay(command.Message)).Forget();
         return command.Message;
     }
 }
 
 [Service]
-public class EchoAsyncHandler : IAsyncCommandHandler<EchoAsync, string>
+public class EchoAsyncHandler(IMessageBus bus) : IAsyncCommandHandler<EchoAsync, string>
 {
-    readonly IMessageBus? bus;
-
-    public EchoAsyncHandler() { }
-
-    public EchoAsyncHandler(IMessageBus bus) => this.bus = bus;
-
-
     public bool CanExecute(EchoAsync command) => true;
 
-    public Task<string> ExecuteAsync(EchoAsync command, CancellationToken cancellation = default)
+    public async ValueTask<string> ExecuteAsync(EchoAsync command, CancellationToken cancellation = default)
     {
-        bus?.Notify(new OnDidSay(command.Message));
-        return Task.FromResult(command.Message);
+        await bus!.NotifyAsync(new OnDidSay(command.Message));
+        return command.Message;
     }
 }
 
 [Service]
 public class NoOpAsyncHandler : IAsyncCommandHandler<NoOpAsync>
 {
     public bool CanExecute(NoOpAsync command) => true;
-    public Task ExecuteAsync(NoOpAsync command, CancellationToken cancellation = default) => Task.CompletedTask;
+    public ValueTask ExecuteAsync(NoOpAsync command, CancellationToken cancellation = default) => new();
 }