Memory allocation documentation for ImmutableDictionary Keys and Values

[sharwell]

Background

As described in dotnet/corefx#246 (and previously in dotnet/corefx#147), the Keys and Values properties of ImmutableDictionary<TKey, TValue> cannot be used without incurring memory allocations on the heap. However, a slight modification of user code provides equivalent behavior without these allocations.

With allocations:

foreach (var key in dictionary.Keys)
{
    ...
}

Without allocations:

foreach (var pair in dictionary)
{
    var key = pair.Key;
}

Suggestion

Since updating the Keys and Values properties to eliminate the allocations would be a breaking change (#246), the only recourse is to update the documentation for these properties to describe steps a user can take to avoid allocations if these properties are used heavily within a particular application.

Caveat

Care must be taken to ensure that the documentation does not read in a way that suggests the Keys and Values properties should not be used. The properties behave properly and would not be even a measurable source of time spent in the application in nearly all cases. This notice is only meant for users making heavy use of these properties who are also actively working to reduce the memory allocations performed within an especially performance-sensitive section of code.

[safern]

Does anyone want to suggest how should the docs be updated if this issue is still relevant?

[AArnott]

I don't see why this is such an important issue. The docs never promise that enumeration of collections or dictionary keys is alloc-free. And as you point out, the API makes this pretty obvious. I've never seen a doc that mentions "this allocates, but this other API doesn't".

[safern]

+1 with @AArnott comment. So then we should probably close this issue. right?

[danmoseley]

+1

[sharwell]

If you can use C# 7, one handy way to address this can be seen in dotnet/roslyn#19126. 👍