[API Proposal]: InitialCapacity for CborWriter

[vcsjones]

Background and motivation

The CborWriter class currently has an internal buffer that grows as data is written to the buffer.

Callers that write large CBOR documents may end up spending a significant amount time constantly re-allocating and copying the buffer as it grows. This was observed in #91969. In this scenario, 98% of the time spent was in Array.Resize.

Callers that know before hand that they are going to write a large CBOR document currently don't have an easy way to give a hint that the internal buffer should be larger than the default.

Conversely, callers that know they are going to create small CBOR documents may give a smaller-than-the-default hint to avoid over-allocating the internal buffer.

This is similar to what we did for AsnWriter except now we are doing it for CborWriter.

API Proposal

namespace System.Formats.Cbor;

public partial class CborWriter {
    public CborWriter(int initialCapacity, CborConformanceMode conformanceMode = CborConformanceMode.Strict, bool convertIndefiniteLengthEncodings = false, bool allowMultipleRootLevelValues = false);
}

API Usage

CborWriter writer = new CborWriter(initialCapacity: 10000000);
// write 1000000 bytes of stuff to the writer.

Alternative Designs

No response

Risks

No response

[ghost]

Tagging subscribers to this area: @dotnet/area-system-formats-cbor, @bartonjs, @vcsjones
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

The CborWriter class currently has an internal buffer that grows as data is written to the buffer.

Callers that write large CBOR documents may end up spending a significant amount time constantly re-allocating and copying the buffer as it grows. This was observed in #91969. In this scenario, 98% of the time spent was in Array.Resize.

Callers that know before hand that they are going to write a large CBOR document currently don't have an easy way to give a hint that the internal buffer should be larger than the default.

Conversely, callers that know they are going to create small CBOR documents may give a smaller-than-the-default hint to avoid over-allocating the internal buffer.

This is similar to what we did for AsnWriter except now we are doing it for CborWriter.

API Proposal

namespace System.Formats.Cbor;

public partial class CborWriter {
    public CborWriter(int initialCapacity, CborConformanceMode conformanceMode = CborConformanceMode.Strict, bool convertIndefiniteLengthEncodings = false, bool allowMultipleRootLevelValues = false);
}

API Usage

CborWriter writer = new CborWriter(initialCapacity: 10000000);
// write 1000000 bytes of stuff to the writer.

Alternative Designs

No response

Risks

No response

Author:	vcsjones
Assignees:	-
Labels:	api-suggestion, area-System.Formats.Cbor
Milestone:	-

[eiriktsarpalis]

Sounds reasonable to me.

[bartonjs]

Video

• We changed from an initial required parameter to a trailing defaulted parameter (and consequently will update the existing constructor to no longer have defaults, and now be never-browsable

namespace System.Formats.Cbor;

public partial class CborWriter {
    [EditorBrowsable(Never)]
    public CborWriter(
       CborConformanceMode conformanceMode,
       bool convertIndefiniteLengthEncodings,
       bool allowMultipleRootLevelValues);

    public CborWriter(
       CborConformanceMode conformanceMode = CborConformanceMode.Strict,
       bool convertIndefiniteLengthEncodings = false,
       bool allowMultipleRootLevelValues = false,
       int initialCapacity = -1);
}