Memory usage improvements/optimizations to Messenger (#3424)

## Follow up for #3230, part of #3428 
<!-- Add the relevant issue number after the "#" mentioned above (for ex: Fixes #1234) which will automatically close the issue once the PR is merged. -->

<!-- Add a brief overview here of the feature/bug & fix. -->

## PR Type
What kind of change does this PR introduce?
<!-- Please uncomment one or more that apply to this PR. -->

- Optimization
<!-- - Bugfix -->
<!-- - Feature -->
<!-- - Code style update (formatting) -->
<!-- - Refactoring (no functional changes, no api changes) -->
<!-- - Build or CI related changes -->
<!-- - Documentation content changes -->
<!-- - Sample app changes -->
<!-- - Other... Please describe: -->

## Overview

This PR includes two main parts: an improvement for the memory pooling buffers, and a refactor of how delegates are registered for message handlers. This last part allows to completely remove local closures for message handlers 🚀

### Memory pooling improvements

We're using memory pooling (by relying on the `ArrayPool<T>` APIs) in the `Messenger` class to achieve an amortized 0-allocation execution of the `Send` method in particular (`UnregisterAll` uses this too). We have code like this:

https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/5bf426523cf456fc13db7b6505c56cad380d5f5f/Microsoft.Toolkit.Mvvm/Messaging/Messenger.cs#L250

https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/5bf426523cf456fc13db7b6505c56cad380d5f5f/Microsoft.Toolkit.Mvvm/Messaging/Messenger.cs#L401

This works just fine, and we do get the 0-allocation after the initial first invocation where we rent the buffer.
There are two downsides here though:
- In the `Send` method, we rent an `Action<TMessage>` buffer, so we'll rent a different buffer for every message type
- Given that these types are either internal or not likely to ever by used by consumers of the library, all these rented buffers would only ever by used by the `Messenger` class itself, and the consumers would not be able to reuse them on their own.

Neither of these points is a big deal and the current implementation is fine, but I think we can do better 😄

**Idea:** let's leverage the fact that arrays are covariant, and only use a single type to solve both problems, like so:

```csharp
object[] maps = ArrayPool<object>.Shared.Rent(count);

// Do stuff, example:
foreach (object obj in maps)
{
    var myActualItem = (SomeFancyTypePossiblyInternal)obj;

    // Do stuff with the item...
}
```

This both allows us to just use `object[]` arrays, which both reduces the total number of rented arrays (as we can reuse them for different message types), and also makes it so that these rented arrays might potentially also be reused by consumers of the library (should they ever need to pool `object[]` arrays), further reducing allocations 🚀

## Benchmarks

Here are some benchmarks comparing the `Messenger` from this PR with the one in the `Preview1`.

### Sending messages

|   Method |       Categories |         Mean |     Error |    StdDev | Ratio | Gen 0 | Gen 1 | Allocated |
|--------- |----------------- |-------------:|----------:|----------:|------:|------:|------:|----------:|
| Old_Send |   DefaultChannel |     161.7 us |   1.52 us |   1.43 us |  1.00 |     - |     - |         - |
| **New_Send** |   DefaultChannel |     **153.9 us** |   1.62 us |   1.43 us |  0.95 |     - |     - |         - |
|          |                  |              |           |           |       |       |       |           |
| Old_Send | MultipleChannels | 148,668.7 us | 886.65 us | 785.99 us |  1.00 |     - |     - |     336 B |
| **New_Send** | MultipleChannels | **138,825.0 us** | 797.61 us | 746.08 us |  0.93 |     - |     - |     336 B |

Performance when sending message is slightly faster than before. Worst case scenario, it's not any slower.

### Registering messages

|       Method |     Mean |   Error |  StdDev | Ratio |    Gen 0 |   Gen 1 | Allocated |
|------------- |---------:|--------:|--------:|------:|---------:|--------:|----------:|
| Old_Register | 443.6 us | 1.73 us | 1.53 us |  1.00 | 113.7695 | 25.3906 | 581.53 KB |
| **New_Register** | **386.1 us** | 2.47 us | 2.31 us |  0.87 |  82.5195 |  4.3945 | **381.53 KB** |

The new version is **13%** faster when registering messages, and uses **34%** less memory 🚀

### Enabled recipient type-specific handlers

One major annoyance for users working with manually registered handlers was the fact that type information was lost.
As in, recipients were registered as just `object` instances, as it was necessary to cast them in the handler every time.
This PR also changes this by adding support for a type parameter to specify the recipient type.
This enables the following change (which is totally optional anyway, you can still just use `object` if you want):

```csharp
// Before
Messenger.Register<MyMessage>(this, (s, m) => ((MyViewModel)s).SomeMethod(m));

// After
Messenger.Register<MyViewModel, MyMessage>(this, (s, m) => s.SomeMethod(m));
```

### Removed local closures

The original implementation used `Action<T>` for handlers, which caused closures to be constantly created whenever the users wanted to access any local member on the registered recipient. This was because the recipient itself needed to be captured too to be accessed from the handlers. This detail also made it more difficult for other devs to implement `IMessenger` if they wanted to use a weak reference system. I've replaced that handler type with a custom delegate, called `MessageHandler`:

https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/32656db1cdd4ddc25e3a88c297ce4062fe64d2ad/Microsoft.Toolkit.Mvvm/Messaging/IMessenger.cs#L10-L22

This delegate also receives the target recipient as input, which allows developers to just use that to access local members, without the need to create closures. The handlers are now essentially static, so the C# compiler can cache the whole delegate too. This is especially useful for the `IRecipient<TMessage>` pattern, as that was previously creating unnecessary closures when registering handlers - that's completely gone now and delegates are cached there as well 🎉

For instance, you can see that here:

https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/32656db1cdd4ddc25e3a88c297ce4062fe64d2ad/Microsoft.Toolkit.Mvvm/Messaging/IMessengerExtensions.cs#L175-L179

We're now using that cached static delegate (will be able to also explicitly mark that as static when C# 9 lands, but it already is) instead of the method group syntax on `recipient.Receive`, which allocated a closure for each invocation.

## PR Checklist

Please check if your PR fulfills the following requirements:

- [X] Tested code with current [supported SDKs](../readme.md#supported)
- [ ] ~~Pull Request has been submitted to the documentation repository [instructions](..\contributing.md#docs). Link: <!-- docs PR link -->~~
- [ ] ~~Sample in sample app has been added / updated (for bug fixes / features)~~
    - [ ] ~~Icon has been created (if new sample) following the [Thumbnail Style Guide and templates](https://github.com/windows-toolkit/WindowsCommunityToolkit-design-assets)~~
- [X] Tests for the changes have been added (for bug fixes / features) (if applicable)
- [X] Header has been added to all new source files (run *build/UpdateHeaders.bat*)
- [X] Contains **NO** breaking changes

Author: msftbot[bot]

Microsoft.Toolkit.Mvvm/ComponentModel/ObservableRecipient.cs

@@ -25,11 +25,11 @@ public abstract class ObservableRecipient : ObservableObject
         /// Initializes a new instance of the <see cref="ObservableRecipient"/> class.
         /// </summary>
         /// <remarks>
-        /// This constructor will produce an instance that will use the <see cref="Messaging.Messenger.Default"/> instance
+        /// This constructor will produce an instance that will use the <see cref="WeakReferenceMessenger.Default"/> instance
         /// to perform requested operations. It will also be available locally through the <see cref="Messenger"/> property.
         /// </remarks>
         protected ObservableRecipient()
-            : this(Messaging.Messenger.Default)
+            : this(WeakReferenceMessenger.Default)
         {
         }
 
@@ -78,7 +78,7 @@ public bool IsActive
         /// <remarks>
         /// The base implementation registers all messages for this recipients that have been declared
         /// explicitly through the <see cref="IRecipient{TMessage}"/> interface, using the default channel.
-        /// For more details on how this works, see the <see cref="MessengerExtensions.RegisterAll"/> method.
+        /// For more details on how this works, see the <see cref="IMessengerExtensions.RegisterAll"/> method.
         /// If you need more fine tuned control, want to register messages individually or just prefer
         /// the lambda-style syntax for message registration, override this method and register manually.
         /// </remarks>

Microsoft.Toolkit.Mvvm/Messaging/IMessenger.cs

@@ -7,8 +7,70 @@
 
 namespace Microsoft.Toolkit.Mvvm.Messaging
 {
+    /// <summary>
+    /// A <see langword="delegate"/> used to represent actions to invoke when a message is received.
+    /// The recipient is given as an input argument to allow message registrations to avoid creating
+    /// closures: if an instance method on a recipient needs to be invoked it is possible to just
+    /// cast the recipient to the right type and then access the local method from that instance.
+    /// </summary>
+    /// <typeparam name="TRecipient">The type of recipient for the message.</typeparam>
+    /// <typeparam name="TMessage">The type of message to receive.</typeparam>
+    /// <param name="recipient">The recipient that is receiving the message.</param>
+    /// <param name="message">The message being received.</param>
+    public delegate void MessageHandler<in TRecipient, in TMessage>(TRecipient recipient, TMessage message)
+        where TRecipient : class
+        where TMessage : class;
+
     /// <summary>
     /// An interface for a type providing the ability to exchange messages between different objects.
+    /// This can be useful to decouple different modules of an application without having to keep strong
+    /// references to types being referenced. It is also possible to send messages to specific channels, uniquely
+    /// identified by a token, and to have different messengers in different sections of an applications.
+    /// In order to use the <see cref="IMessenger"/> functionalities, first define a message type, like so:
+    /// <code>
+    /// public sealed class LoginCompletedMessage { }
+    /// </code>
+    /// Then, register your a recipient for this message:
+    /// <code>
+    /// Messenger.Default.Register&lt;MyRecipientType, LoginCompletedMessage&gt;(this, (r, m) =>
+    /// {
+    ///     // Handle the message here...
+    /// });
+    /// </code>
+    /// The message handler here is a lambda expression taking two parameters: the recipient and the message.
+    /// This is done to avoid the allocations for the closures that would've been generated if the expression
+    /// had captured the current instance. The recipient type parameter is used so that the recipient can be
+    /// directly accessed within the handler without the need to manually perform type casts. This allows the
+    /// code to be less verbose and more reliable, as all the checks are done just at build time. If the handler
+    /// is defined within the same type as the recipient, it is also possible to directly access private members.
+    /// This allows the message handler to be a static method, which enables the C# compiler to perform a number
+    /// of additional memory optimizations (such as caching the delegate, avoiding unnecessary memory allocations).
+    /// Finally, send a message when needed, like so:
+    /// <code>
+    /// Messenger.Default.Send&lt;LoginCompletedMessage&gt;();
+    /// </code>
+    /// Additionally, the method group syntax can also be used to specify the message handler
+    /// to invoke when receiving a message, if a method with the right signature is available
+    /// in the current scope. This is helpful to keep the registration and handling logic separate.
+    /// Following up from the previous example, consider a class having this method:
+    /// <code>
+    /// private static void Receive(MyRecipientType recipient, LoginCompletedMessage message)
+    /// {
+    ///     // Handle the message there
+    /// }
+    /// </code>
+    /// The registration can then be performed in a single line like so:
+    /// <code>
+    /// Messenger.Default.Register(this, Receive);
+    /// </code>
+    /// The C# compiler will automatically convert that expression to a <see cref="MessageHandler{TRecipient,TMessage}"/> instance
+    /// compatible with <see cref="IMessengerExtensions.Register{TRecipient,TMessage}(IMessenger,TRecipient,MessageHandler{TRecipient,TMessage})"/>.
+    /// This will also work if multiple overloads of that method are available, each handling a different
+    /// message type: the C# compiler will automatically pick the right one for the current message type.
+    /// It is also possible to register message handlers explicitly using the <see cref="IRecipient{TMessage}"/> interface.
+    /// To do so, the recipient just needs to implement the interface and then call the
+    /// <see cref="IMessengerExtensions.RegisterAll(IMessenger,object)"/> extension, which will automatically register
+    /// all the handlers that are declared by the recipient type. Registration for individual handlers is supported as well.
     /// </summary>
     public interface IMessenger
     {
@@ -28,13 +90,15 @@ bool IsRegistered<TMessage, TToken>(object recipient, TToken token)
         /// <summary>
         /// Registers a recipient for a given type of message.
         /// </summary>
+        /// <typeparam name="TRecipient">The type of recipient for the message.</typeparam>
         /// <typeparam name="TMessage">The type of message to receive.</typeparam>
         /// <typeparam name="TToken">The type of token to use to pick the messages to receive.</typeparam>
         /// <param name="recipient">The recipient that will receive the messages.</param>
         /// <param name="token">A token used to determine the receiving channel to use.</param>
-        /// <param name="action">The <see cref="Action{T}"/> to invoke when a message is received.</param>
+        /// <param name="handler">The <see cref="MessageHandler{TRecipient,TMessage}"/> to invoke when a message is received.</param>
         /// <exception cref="InvalidOperationException">Thrown when trying to register the same message twice.</exception>
-        void Register<TMessage, TToken>(object recipient, TToken token, Action<TMessage> action)
+        void Register<TRecipient, TMessage, TToken>(TRecipient recipient, TToken token, MessageHandler<TRecipient, TMessage> handler)
+            where TRecipient : class
             where TMessage : class
             where TToken : IEquatable<TToken>;
 
@@ -83,6 +147,14 @@ TMessage Send<TMessage, TToken>(TMessage message, TToken token)
             where TMessage : class
             where TToken : IEquatable<TToken>;
 
+        /// <summary>
+        /// Performs a cleanup on the current messenger.
+        /// Invoking this method does not unregister any of the currently registered
+        /// recipient, and it can be used to perform cleanup operations such as
+        /// trimming the internal data structures of a messenger implementation.
+        /// </summary>
+        void Cleanup();
+
         /// <summary>
         /// Resets the <see cref="IMessenger"/> instance and unregisters all the existing recipients.
         /// </summary>

Microsoft.Toolkit.Mvvm/Messaging/MessengerExtensions.cs renamed to Microsoft.Toolkit.Mvvm/Messaging/IMessengerExtensions.cs

@@ -8,19 +8,20 @@
 using System.Linq.Expressions;
 using System.Reflection;
 using System.Runtime.CompilerServices;
+using Microsoft.Toolkit.Mvvm.Messaging.Internals;
 
 namespace Microsoft.Toolkit.Mvvm.Messaging
 {
     /// <summary>
     /// Extensions for the <see cref="IMessenger"/> type.
     /// </summary>
-    public static partial class MessengerExtensions
+    public static class IMessengerExtensions
     {
         /// <summary>
         /// A class that acts as a container to load the <see cref="MethodInfo"/> instance linked to
         /// the <see cref="Register{TMessage,TToken}(IMessenger,IRecipient{TMessage},TToken)"/> method.
         /// This class is needed to avoid forcing the initialization code in the static constructor to run as soon as
-        /// the <see cref="MessengerExtensions"/> type is referenced, even if that is done just to use methods
+        /// the <see cref="IMessengerExtensions"/> type is referenced, even if that is done just to use methods
         /// that do not actually require this <see cref="MethodInfo"/> instance to be available.
         /// We're effectively using this type to leverage the lazy loading of static constructors done by the runtime.
         /// </summary>
@@ -32,7 +33,7 @@ private static class MethodInfos
             static MethodInfos()
             {
                 RegisterIRecipient = (
-                    from methodInfo in typeof(MessengerExtensions).GetMethods()
+                    from methodInfo in typeof(IMessengerExtensions).GetMethods()
                     where methodInfo.Name == nameof(Register) &&
                           methodInfo.IsGenericMethod &&
                           methodInfo.GetGenericArguments().Length == 2
@@ -174,7 +175,7 @@ static Action<IMessenger, object, TToken> GetRegistrationAction(Type type, Metho
         public static void Register<TMessage>(this IMessenger messenger, IRecipient<TMessage> recipient)
             where TMessage : class
         {
-            messenger.Register<TMessage, Unit>(recipient, default, recipient.Receive);
+            messenger.Register<IRecipient<TMessage>, TMessage, Unit>(recipient, default, (r, m) => r.Receive(m));
         }
 
         /// <summary>
@@ -191,7 +192,7 @@ public static void Register<TMessage, TToken>(this IMessenger messenger, IRecipi
             where TMessage : class
             where TToken : IEquatable<TToken>
         {
-            messenger.Register<TMessage, TToken>(recipient, token, recipient.Receive);
+            messenger.Register<IRecipient<TMessage>, TMessage, TToken>(recipient, token, (r, m) => r.Receive(m));
         }
 
         /// <summary>
@@ -200,13 +201,47 @@ public static void Register<TMessage, TToken>(this IMessenger messenger, IRecipi
         /// <typeparam name="TMessage">The type of message to receive.</typeparam>
         /// <param name="messenger">The <see cref="IMessenger"/> instance to use to register the recipient.</param>
         /// <param name="recipient">The recipient that will receive the messages.</param>
-        /// <param name="action">The <see cref="Action{T}"/> to invoke when a message is received.</param>
+        /// <param name="handler">The <see cref="MessageHandler{TRecipient,TMessage}"/> to invoke when a message is received.</param>
         /// <exception cref="InvalidOperationException">Thrown when trying to register the same message twice.</exception>
         /// <remarks>This method will use the default channel to perform the requested registration.</remarks>
-        public static void Register<TMessage>(this IMessenger messenger, object recipient, Action<TMessage> action)
+        public static void Register<TMessage>(this IMessenger messenger, object recipient, MessageHandler<object, TMessage> handler)
             where TMessage : class
         {
-            messenger.Register(recipient, default(Unit), action);
+            messenger.Register(recipient, default(Unit), handler);
+        }
+
+        /// <summary>
+        /// Registers a recipient for a given type of message.
+        /// </summary>
+        /// <typeparam name="TRecipient">The type of recipient for the message.</typeparam>
+        /// <typeparam name="TMessage">The type of message to receive.</typeparam>
+        /// <param name="messenger">The <see cref="IMessenger"/> instance to use to register the recipient.</param>
+        /// <param name="recipient">The recipient that will receive the messages.</param>
+        /// <param name="handler">The <see cref="MessageHandler{TRecipient,TMessage}"/> to invoke when a message is received.</param>
+        /// <exception cref="InvalidOperationException">Thrown when trying to register the same message twice.</exception>
+        /// <remarks>This method will use the default channel to perform the requested registration.</remarks>
+        public static void Register<TRecipient, TMessage>(this IMessenger messenger, TRecipient recipient, MessageHandler<TRecipient, TMessage> handler)
+            where TRecipient : class
+            where TMessage : class
+        {
+            messenger.Register(recipient, default(Unit), handler);
+        }
+
+        /// <summary>
+        /// Registers a recipient for a given type of message.
+        /// </summary>
+        /// <typeparam name="TMessage">The type of message to receive.</typeparam>
+        /// <typeparam name="TToken">The type of token to use to pick the messages to receive.</typeparam>
+        /// <param name="messenger">The <see cref="IMessenger"/> instance to use to register the recipient.</param>
+        /// <param name="recipient">The recipient that will receive the messages.</param>
+        /// <param name="token">A token used to determine the receiving channel to use.</param>
+        /// <param name="handler">The <see cref="MessageHandler{TRecipient,TMessage}"/> to invoke when a message is received.</param>
+        /// <exception cref="InvalidOperationException">Thrown when trying to register the same message twice.</exception>
+        public static void Register<TMessage, TToken>(this IMessenger messenger, object recipient, TToken token, MessageHandler<object, TMessage> handler)
+            where TMessage : class
+            where TToken : IEquatable<TToken>
+        {
+            messenger.Register(recipient, token, handler);
         }
 
         /// <summary>

Microsoft.Toolkit.Mvvm/Messaging/Microsoft.Collections.Extensions/DictionarySlim{TKey,TValue}.cs renamed to Microsoft.Toolkit.Mvvm/Messaging/Internals/Microsoft.Collections.Extensions/DictionarySlim{TKey,TValue}.cs

@@ -130,7 +130,11 @@ public void Clear()
             this.entries = InitialEntries;
         }
 
-        /// <inheritdoc cref="Dictionary{TKey,TValue}.ContainsKey"/>
+        /// <summary>
+        /// Checks whether or not the dictionary contains a pair with a specified key.
+        /// </summary>
+        /// <param name="key">The key to look for.</param>
+        /// <returns>Whether or not the key was present in the dictionary.</returns>
         public bool ContainsKey(TKey key)
         {
             Entry[] entries = this.entries;
@@ -176,7 +180,18 @@ public bool TryGetValue(TKey key, out TValue? value)
         }
 
         /// <inheritdoc/>
-        public bool TryRemove(TKey key, out object? result)
+        public bool TryRemove(TKey key)
+        {
+            return TryRemove(key, out _);
+        }
+
+        /// <summary>
+        /// Tries to remove a value with a specified key, if present.
+        /// </summary>
+        /// <param name="key">The key of the value to remove.</param>
+        /// <param name="result">The removed value, if it was present.</param>
+        /// <returns>Whether or not the key was present.</returns>
+        public bool TryRemove(TKey key, out TValue? result)
         {
             Entry[] entries = this.entries;
             int bucketIndex = key.GetHashCode() & (this.buckets.Length - 1);
@@ -218,13 +233,6 @@ public bool TryRemove(TKey key, out object? result)
             return false;
         }
 
-        /// <inheritdoc/>
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public bool Remove(TKey key)
-        {
-            return TryRemove(key, out _);
-        }
-
         /// <summary>
         /// Gets the value for the specified key, or, if the key is not present,
         /// adds an entry and returns the value by ref. This makes it possible to

Microsoft.Toolkit.Mvvm/Messaging/Microsoft.Collections.Extensions/HashHelpers.cs renamed to Microsoft.Toolkit.Mvvm/Messaging/Internals/Microsoft.Collections.Extensions/HashHelpers.cs

@@ -14,18 +14,10 @@ internal interface IDictionarySlim<in TKey> : IDictionarySlim
         where TKey : IEquatable<TKey>
     {
         /// <summary>
-        /// Tries to remove a value with a specified key.
+        /// Tries to remove a value with a specified key, if present.
         /// </summary>
         /// <param name="key">The key of the value to remove.</param>
-        /// <param name="result">The removed value, if it was present.</param>
-        /// <returns>.Whether or not the key was present.</returns>
-        bool TryRemove(TKey key, out object? result);
-
-        /// <summary>
-        /// Removes an item from the dictionary with the specified key, if present.
-        /// </summary>
-        /// <param name="key">The key of the item to remove.</param>
-        /// <returns>Whether or not an item was removed.</returns>
-        bool Remove(TKey key);
+        /// <returns>Whether or not the key was present.</returns>
+        bool TryRemove(TKey key);
     }
 }