[API Proposal]: Introduce IResettable to streamline object pool usage

[geeknoid]

Background and motivation

We use a lot of object pools in our environment and its clumsy to have to implement dedicated policy types when we generally want a single behavior applied to a large variety of object types. We adopted a solution of having all these objects declare themselves as IResettable and then a single policy suffices to deal with these objects

API Proposal

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>
    /// <remarks>
    /// In general, this method is not expected to be thread-safe.
    /// </remarks>
    void Reset();
}

/// <summary>
/// An object pool policy for resettable objects.
/// </summary>
public sealed class ResettablePooledObjectPolicy<T> : PooledObjectPolicy<T>
    where T : notnull, IResettable, new()
{
    public static ResettablePooledObjectPolicy<T> Instance { get; } = new();

    private ResettablePooledObjectPolicy()
    {
    }

    public override T Create() => new();

    public override bool Return(T obj)
    {
        obj.Reset();
        return true;
    }
}

API Usage

// a resettable object is one that logically can come back to its initial state
internal class MyState : IResettable
{
    private readonly List<int> _data = new();
    public void Add(int value) { _data.Add(value); }
    public void Reset() { _data.Clear(); }
}

var pool = ObjectPool.Create<MyState>(ResettableObjectPoolPolicy<MyState>.Instance);

// or alternatively, there could be a new method on ObjectPool, which requires less typing...
var pool = ObjectPool.CreateResettable<MyState>();

Alternative Designs

No response

Risks

No response

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[joperezr]

cc: @Tratcher

[xiaoyuvax]

I also met similar challenge to use instances returned from the object pool, cos they contain old property values and references to other objects, which may lead to problems, if not intialized.
but the IResettable solution requires implementing Reset() method for each object, it's a lot of labor if u've got a lot of types, cos u have to initialize each member of a type, some of which may be of reference to other types, as is complicated.

So far my solution is an extenstion method which cleans(resets).

 public static T Clean<T>(this T obj)  // where T: IResetable    <-- U can limit it to certain interface
        {
            foreach (var p in obj.GetType().GetProperties().Where(i => i.CanWrite))
               p.SetValue(obj, default);
//In my opinion, references in properties can be simply reset as null, the code reusing these properties is responsible to specify their references, e.g. from ObjectPool. 

            if (obj is IResetable resetable) resetable.Reset();      // <- Reset() can be done here.
            // thus Reset() can only contains fewer necessary code specific to each type, instead of refilling up all properties.
            return obj;
        }

For performance consideration：
1）Above Clean() method is not required on all cases, e.g. when the fetched object would be fully overwritten by subsequent code, while the IResetable solution costs more in such case.
2）DefaultObjectPool should seek lowlevel solution to reset the instance as if the object were created like new(), for neither this Clean() nor IResetable solution is not performance friendly.

Anyway, I adopted the Reset() method, but the ObjectPoolPolicy model is not favorable for my case.

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[halter73]

Could the default policy call IResettable.Reset() on return if the object happens to implement the interface? Since this is a new interface, this should be non breaking.

@JamesNK asks if Reset() should return a boolean to indicate success? Like TryReset? Could be useful for things like CancellationTokenSource.

Another option is to keep the ResettablePooledObjectPolicy type, and add a public ResettablePooledObjectPolicy(Func<T, bool> tryReset). This way it could work for types you don't own. We might even be able to replat the StringBuilder policy on it and get rid of the interface.

[xiaoyuvax]

ah, this "default policy call IResettable.Reset() " if detected, is preferable, avoiding introducing new Pool or Policy.

I also suggest Object.Get(bool NoReset=true), as ignores calling the Reset() method, and fetch an object as it is, as to improve performance. If this instance is to be fully overwritten later in the code, it doesn't need a reset.

[geeknoid]

Having the default policy call Reset would require adding a type test in the existing paths, which would slow things down a teeny bit.

Having the Reset function return a boolean is a reasonable idea, although it seems fairly niche. Nevertheless the semantics would be clear. If Reset returns false, then the object is dropped on the floor and not added to the pool.