dotnet / dotnet/runtime

[API Proposal]: Add `System.Reflection.Metadata.Ecma335.MetadataBuilder.Clear`.

Open
#127,404 2 comments 1 reaction 1 assignee Claimed by @teo-tsirpanis View on GitHub
api-suggestion area-System.Reflection.Metadata
Dominant language
C#
Stars
18.3k
Forks
5.6k
PR merge metrics
PR metrics pending

Description

### Background and motivation

`MetadataBuilder` is a large type holding references to several objects, which might include LOH-allocated arrays. Allowing the object to be reused across metadata emits would help with reducing GC pressure. This requires an API to clear the internal state of a `MetadataBuilder`, which I am proposing.

### API Proposal

```csharp
namespace System.Reflection.Metadata.Ecma335;

public class MetadataBuilder
{
// Uses the same parameters with the constructor.
// The BlobBuilder factory delegate proposed in #100418 is not very useful to reassign
// when clearing the metadata builder, so it was omitted.
public void Clear(int userStringHeapStartOffset = 0, int stringHeapStartOffset = 0, int blobHeapStartOffset = 0, int guidHeapStartOffset = 0);
}
```

### API Usage

This API can be used by a pool of `MetadataBuilder` objects. Here's an illustrative example:

```csharp
internal static class MetadataBuilderPool
{
private static readonly ConcurrentQueue s_pool = new();

public static MetadataBuilder Rent()
{
if (!s_pool.TryDequeue(out var builder))
{
builder = new MetadataBuilder();
}
return builder;
}

public static void Return(MetadataBuilder builder)
{
if (s_pool.Count >= 16)
{
return;
}
builder.Clear();
s_pool.Enqueue(builder);
}
}
```

### Alternative Designs

* Do not add parameters to `Clear`, and stick with the heap offsets specified in the constructor. This would preclude using pooled `MetadataBuilder`s when emitting EnC deltas.
* Automatically reset the `MetadataBuilder`'s state after serializing its data through `MetadataRootBuilder`, `PortablePdbBuilder`, or another API using these. I'm not a big fan of silently changing behavior like this, but it might make sense here, since serializing a `MetadataBuilder` multiple times already fails.

### Risks

_No response_

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.