Introduce the IResettable type. (#46426)

Reference #44901.

Co-authored-by: Martin Taillefer <[email protected]>

Author: geeknoid

src/ObjectPool/src/DefaultPooledObjectPolicy.cs

@@ -18,8 +18,11 @@ public override T Create()
     /// <inheritdoc />
     public override bool Return(T obj)
     {
-        // DefaultObjectPool<T> doesn't call 'Return' for the default policy.
-        // So take care adding any logic to this method, as it might require changes elsewhere.
+        if (obj is IResettable resettable)
+        {
+            return resettable.TryReset();
+        }
+
         return true;
     }
 }

src/ObjectPool/src/IResettable.cs

@@ -0,0 +1,19 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.Extensions.ObjectPool;
+
+/// <summary>
+/// Defines a method to reset an object to its initial state.
+/// </summary>
+public interface IResettable
+{
+    /// <summary>
+    /// Reset the object to a neutral state, semantically similar to when the object was first constructed.
+    /// </summary>
+    /// <returns><see langword="true" /> if the object was able to reset itself, otherwise <see langword="false" />.</returns>
+    /// <remarks>
+    /// In general, this method is not expected to be thread-safe.
+    /// </remarks>
+    bool TryReset();
+}

src/ObjectPool/src/PublicAPI.Unshipped.txt

@@ -1 +1,3 @@
 #nullable enable
+Microsoft.Extensions.ObjectPool.IResettable
+Microsoft.Extensions.ObjectPool.IResettable.TryReset() -> bool

src/ObjectPool/test/DefaultObjectPoolTest.cs

@@ -69,6 +69,34 @@ public void DefaultObjectPool_Return_RejectedByPolicy()
         Assert.NotSame(list1, list2);
     }
 
+    [Fact]
+    public static void DefaultObjectPool_Honors_IResettable()
+    {
+        var p = new DefaultObjectPool<Resettable>(new DefaultPooledObjectPolicy<Resettable>());
+        var r = new Resettable();
+
+        r.ResetReturnValue = false;
+        p.Return(r);
+        Assert.Equal(1, r.ResetCallCount);
+        Assert.NotSame(r, p.Get());
+
+        r.ResetReturnValue = true;
+        p.Return(r);
+        Assert.Equal(2, r.ResetCallCount);
+        Assert.Same(r, p.Get());
+    }
+
+    private sealed class Resettable : IResettable
+    {
+        public int ResetCallCount { get; set; }
+        public bool ResetReturnValue { get; set; }
+        public bool TryReset()
+        {
+            ResetCallCount++;
+            return ResetReturnValue;
+        }
+    }
+
     private class ListPolicy : IPooledObjectPolicy<List<int>>
     {
         public List<int> Create()