Provide a way to reset an ArrayBufferWriter without clearing the underlying memory

[john-h-k]

Background and Motivation

Currently there is no way to reset an ArrayBufferWriter<T> without zeroing the underlying memory, which can be expensive and an entirely unnecessary cost often.

Proposed API

namespace System.Buffers
{
    public class ArrayBufferWriter<T> : IBufferWriter<T>
    {
+        public void Reset();
    }
}

Usage Examples

When building short-lived buffers in high performance scenarios (for example, to generate command buffers to be sent over PCIE or network to control physical devices), being able to quickly reset the buffer writer is helpful, and zeroing is an unnecessary expense.

Alternative Designs

It could alternatively be an overload of Clear:

public void Clear(bool zeroBackingArray);

Risks

Types which contain references should probably still be cleared to allow collection.

[ghost]

Tagging subscribers to this area: @tannergooding, @pgovind, @GrabYourPitchforks
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and Motivation

Currently there is no way to reset an ArrayBufferWriter<T> without zeroing the underlying memory, which can be expensive and an entirely unnecessary cost often.

Proposed API

namespace System.Buffers
{
    public class ArrayBufferWriter<T> : IBufferWriter<T>
    {
+        public void Reset();
    }
}

Usage Examples

When building short-lived buffers in high performance scenarios (for example, to generate command buffers to be sent over PCIE or network to control physical devices), being able to quickly reset the buffer writer is helpful, and zeroing is an unnecessary expense.

Alternative Designs

It could alternatively be an overload of Clear:

public void Clear(bool zeroBackingArray);

Risks

Types which contain references should probably still be cleared to allow collection.

Author:	john-h-k
Assignees:	-
Labels:	api-suggestion, area-System.Buffers, untriaged
Milestone:	-

[geeknoid]

I was just coming here to make exactly the same suggestion. We end up having a custom implementation of ArrayBufferWriter in our project which uses a Reset method. It'd be great if we didn't need that.

[GrabYourPitchforks]

@tannergooding @pgovind any aversion to marking this ready for review? Seems like a straightforward enough proposal.

/cc @davidfowl in case you'd find it interesting in your projects.

[stephentoub]

I have to ask... do we even need a new API? Could we instead just retcon the design:
stephentoub@5a62634
and say that "clearing" is just like List<T>.Clear semantics, which only zeros if it contains a reference? And if we did that, does that cover enough ground that we could avoid the additional (potentially confusing Reset vs Clear) API?

[GrabYourPitchforks]

In theory this could be a behavioral break, where people clear an array writer, populate some sparse elements, then advance it again, assuming that all untouched elements will have a default(T) value. Thinking back to #30649. But this is slightly different than that issue, where here we'd not be populating the underlying array with arbitrary uninitialized data. The data would still be initialized by virtue of the fact that it was supplied by the previous caller.

So maybe the theoretical break isn't a huge concern? We could always make the change now since it's early preview and monitor feedback.

[geeknoid]

@stephentoub Yeah, the implementation of my Reset function in fact has:

public void Reset()
{
#if NETFW_OR_NETSTD2
    _buffer.AsSpan(0, WrittenCount).Clear();
#else
    if (RuntimeHelpers.IsReferenceOrContainsReferences<T>())
    {
        _buffer.AsSpan(0, WrittenCount).Clear();
    }
#endif

    WrittenCount = 0;
}

But given that Clear has been systematically setting the array to 0, it is definitely a breaking change to stop doing that for primitive types.

[geeknoid]

The difference with List.Clear is that the unused portion of the array inside of List is not visible to the user of the abstraction. The array underlying ArrayBufferWriter is visible to the outside world

[tannergooding]

@GrabYourPitchforks, I don't have an issue here. However, if we can retcon or overload the existing design like Stephen suggested, that would be better 😄

[GrabYourPitchforks]

How about we mark this ready-for-review, bring it to API review, and discuss the compat concerns there regarding the behavioral change? Either collectively we can say "new API approved!" or "let's repurpose the existing API." Either way it's forward progress on this issue.

[terrajobst]

Video

• Let's go with ResetWrittenCount()

namespace System.Buffers;

public partial class ArrayBufferWriter<T> : IBufferWriter<T>
{
    public void ResetWrittenCount();
}